<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow-IPC: transport/struc/channel.hpp Source File</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow-IPC<span id="projectnumber">&#160;2.0.0</span>
   </div>
   <div id="projectbrief">Flow-IPC project: Full implementation reference.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="dir_58e412aa7ace8e71fc01678dc8765e7c.html">transport</a></li><li class="navelem"><a class="el" href="dir_a98fddea045b8b2df4350ebb1d483bf8.html">struc</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="headertitle"><div class="title">channel.hpp</div></div>
</div><!--header-->
<div class="contents">
<a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html">Go to the documentation of this file.</a><div class="fragment"><div class="line"><a id="l00001" name="l00001"></a><span class="lineno">    1</span><span class="comment">/* Flow-IPC: Structured Transport</span></div>
<div class="line"><a id="l00002" name="l00002"></a><span class="lineno">    2</span><span class="comment"> * Copyright (c) 2023 Akamai Technologies, Inc.; and other contributors.</span></div>
<div class="line"><a id="l00003" name="l00003"></a><span class="lineno">    3</span><span class="comment"> * Each commit is copyright by its respective author or author&#39;s employer.</span></div>
<div class="line"><a id="l00004" name="l00004"></a><span class="lineno">    4</span><span class="comment"> *</span></div>
<div class="line"><a id="l00005" name="l00005"></a><span class="lineno">    5</span><span class="comment"> * Licensed under the MIT License:</span></div>
<div class="line"><a id="l00006" name="l00006"></a><span class="lineno">    6</span><span class="comment"> *</span></div>
<div class="line"><a id="l00007" name="l00007"></a><span class="lineno">    7</span><span class="comment"> * Permission is hereby granted, free of charge, to any person obtaining a copy</span></div>
<div class="line"><a id="l00008" name="l00008"></a><span class="lineno">    8</span><span class="comment"> * of this software and associated documentation files (the &quot;Software&quot;), to deal</span></div>
<div class="line"><a id="l00009" name="l00009"></a><span class="lineno">    9</span><span class="comment"> * in the Software without restriction, including without limitation the rights</span></div>
<div class="line"><a id="l00010" name="l00010"></a><span class="lineno">   10</span><span class="comment"> * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell</span></div>
<div class="line"><a id="l00011" name="l00011"></a><span class="lineno">   11</span><span class="comment"> * copies of the Software, and to permit persons to whom the Software is</span></div>
<div class="line"><a id="l00012" name="l00012"></a><span class="lineno">   12</span><span class="comment"> * furnished to do so, subject to the following conditions:</span></div>
<div class="line"><a id="l00013" name="l00013"></a><span class="lineno">   13</span><span class="comment"> *</span></div>
<div class="line"><a id="l00014" name="l00014"></a><span class="lineno">   14</span><span class="comment"> * The above copyright notice and this permission notice shall be included in</span></div>
<div class="line"><a id="l00015" name="l00015"></a><span class="lineno">   15</span><span class="comment"> * all copies or substantial portions of the Software.</span></div>
<div class="line"><a id="l00016" name="l00016"></a><span class="lineno">   16</span><span class="comment"> *</span></div>
<div class="line"><a id="l00017" name="l00017"></a><span class="lineno">   17</span><span class="comment"> * THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR</span></div>
<div class="line"><a id="l00018" name="l00018"></a><span class="lineno">   18</span><span class="comment"> * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,</span></div>
<div class="line"><a id="l00019" name="l00019"></a><span class="lineno">   19</span><span class="comment"> * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE</span></div>
<div class="line"><a id="l00020" name="l00020"></a><span class="lineno">   20</span><span class="comment"> * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER</span></div>
<div class="line"><a id="l00021" name="l00021"></a><span class="lineno">   21</span><span class="comment"> * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,</span></div>
<div class="line"><a id="l00022" name="l00022"></a><span class="lineno">   22</span><span class="comment"> * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN</span></div>
<div class="line"><a id="l00023" name="l00023"></a><span class="lineno">   23</span><span class="comment"> * THE SOFTWARE. */</span></div>
<div class="line"><a id="l00024" name="l00024"></a><span class="lineno">   24</span><span class="comment"></span> </div>
<div class="line"><a id="l00025" name="l00025"></a><span class="lineno">   25</span><span class="comment">/// @file</span></div>
<div class="line"><a id="l00026" name="l00026"></a><span class="lineno">   26</span><span class="comment"></span><span class="preprocessor">#pragma once</span></div>
<div class="line"><a id="l00027" name="l00027"></a><span class="lineno">   27</span> </div>
<div class="line"><a id="l00028" name="l00028"></a><span class="lineno">   28</span><span class="preprocessor">#include &quot;<a class="code" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp.html">ipc/transport/struc/sync_io/channel.hpp</a>&quot;</span></div>
<div class="line"><a id="l00029" name="l00029"></a><span class="lineno">   29</span><span class="preprocessor">#include &lt;flow/async/single_thread_task_loop.hpp&gt;</span></div>
<div class="line"><a id="l00030" name="l00030"></a><span class="lineno">   30</span><span class="preprocessor">#include &lt;boost/move/make_unique.hpp&gt;</span></div>
<div class="line"><a id="l00031" name="l00031"></a><span class="lineno">   31</span> </div>
<div class="line"><a id="l00032" name="l00032"></a><span class="lineno">   32</span><span class="keyword">namespace </span><a class="code hl_namespace" href="namespaceipc_1_1transport_1_1struc.html">ipc::transport::struc</a></div>
<div class="line"><a id="l00033" name="l00033"></a><span class="lineno">   33</span>{</div>
<div class="line"><a id="l00034" name="l00034"></a><span class="lineno">   34</span> </div>
<div class="line"><a id="l00035" name="l00035"></a><span class="lineno">   35</span><span class="comment">// Types.</span></div>
<div class="line"><a id="l00036" name="l00036"></a><span class="lineno">   36</span><span class="comment"></span> </div>
<div class="line"><a id="l00037" name="l00037"></a><span class="lineno">   37</span><span class="comment">/**</span></div>
<div class="line"><a id="l00038" name="l00038"></a><span class="lineno">   38</span><span class="comment"> * Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel over which</span></div>
<div class="line"><a id="l00039" name="l00039"></a><span class="lineno">   39</span><span class="comment"> * *unstructured* messages and optionally native handles can be transported), this template is the central pillar of the</span></div>
<div class="line"><a id="l00040" name="l00040"></a><span class="lineno">   40</span><span class="comment"> * ipc::transport::struc (*structured layer*), capable of communicating structured capnp-schema-based messages (and</span></div>
<div class="line"><a id="l00041" name="l00041"></a><span class="lineno">   41</span><span class="comment"> * native handles).</span></div>
<div class="line"><a id="l00042" name="l00042"></a><span class="lineno">   42</span><span class="comment"> *</span></div>
<div class="line"><a id="l00043" name="l00043"></a><span class="lineno">   43</span><span class="comment"> * @see sync_io::Channel and util::sync_io doc headers.  The latter describes a general pattern which</span></div>
<div class="line"><a id="l00044" name="l00044"></a><span class="lineno">   44</span><span class="comment"> *      the former implements.  In general we recommend you use a `*this` rather than a sync_io::Channel --</span></div>
<div class="line"><a id="l00045" name="l00045"></a><span class="lineno">   45</span><span class="comment"> *      but you may have particular needs (summarized in util::sync_io doc header) that would make you decide</span></div>
<div class="line"><a id="l00046" name="l00046"></a><span class="lineno">   46</span><span class="comment"> *      otherwise.</span></div>
<div class="line"><a id="l00047" name="l00047"></a><span class="lineno">   47</span><span class="comment"> *</span></div>
<div class="line"><a id="l00048" name="l00048"></a><span class="lineno">   48</span><span class="comment"> * ### Context (short version) ###</span></div>
<div class="line"><a id="l00049" name="l00049"></a><span class="lineno">   49</span><span class="comment"> * struc::Channel (and its `sync_io` counterpart -- and, internally, its core) along with Msg_out and Msg_in</span></div>
<div class="line"><a id="l00050" name="l00050"></a><span class="lineno">   50</span><span class="comment"> * essentially *are* the ipc::transport structured layer.  We also</span></div>
<div class="line"><a id="l00051" name="l00051"></a><span class="lineno">   51</span><span class="comment"> * suspect that (and designed ipc::transport accordingly) most users of ipc::transport, or arguably even Flow-IPC</span></div>
<div class="line"><a id="l00052" name="l00052"></a><span class="lineno">   52</span><span class="comment"> * at large, will mostly care about the work they can do with struc::Channel and nothing else.  Users just</span></div>
<div class="line"><a id="l00053" name="l00053"></a><span class="lineno">   53</span><span class="comment"> * want to send structured messages (and sometimes native handles) in some forward-compatible protocol.  Everything</span></div>
<div class="line"><a id="l00054" name="l00054"></a><span class="lineno">   54</span><span class="comment"> * else -- sessions, unstructured-layer channels, the queues and/or socket streams comprised by those channels --</span></div>
<div class="line"><a id="l00055" name="l00055"></a><span class="lineno">   55</span><span class="comment"> * are the necessary but ideally-ignored-most-of-the-time *means* leading to the *ultimate end* of having a working</span></div>
<div class="line"><a id="l00056" name="l00056"></a><span class="lineno">   56</span><span class="comment"> * struc::Channel over which to exchange that structured stuff with the peer&#39;s struc::Channel counterpart.</span></div>
<div class="line"><a id="l00057" name="l00057"></a><span class="lineno">   57</span><span class="comment"> *</span></div>
<div class="line"><a id="l00058" name="l00058"></a><span class="lineno">   58</span><span class="comment"> * ### Context (more in-depth) ###</span></div>
<div class="line"><a id="l00059" name="l00059"></a><span class="lineno">   59</span><span class="comment"> * This has certain broad implications.  Suppose one first familiarizes themselves with the unstructured layer</span></div>
<div class="line"><a id="l00060" name="l00060"></a><span class="lineno">   60</span><span class="comment"> * (concepts Blob_sender, Blob_receiver, Native_handle_sender, Native_handle_receiver; bundling class template</span></div>
<div class="line"><a id="l00061" name="l00061"></a><span class="lineno">   61</span><span class="comment"> * transport::Channel; concept impls -- classes/class templates Native_socket_stream, Blob_stream_mq_sender,</span></div>
<div class="line"><a id="l00062" name="l00062"></a><span class="lineno">   62</span><span class="comment"> * Blob_stream_mq_receiver; low-level details like the MQ-related API and server class Native_socket_stream_acceptor).</span></div>
<div class="line"><a id="l00063" name="l00063"></a><span class="lineno">   63</span><span class="comment"> * If one indeed is familiar with that whole unstructured API, they&#39;ll note: struc::Channel API is quite</span></div>
<div class="line"><a id="l00064" name="l00064"></a><span class="lineno">   64</span><span class="comment"> * different.  Particularly it&#39;s very different in terms of how one handles *in-messages* (receiving).  To wit:</span></div>
<div class="line"><a id="l00065" name="l00065"></a><span class="lineno">   65</span><span class="comment"> *   - The unstructured APIs are roughly boost.asio-like (though in fact *not* requiring any integration with actual</span></div>
<div class="line"><a id="l00066" name="l00066"></a><span class="lineno">   66</span><span class="comment"> *     boost.asio).  That is:</span></div>
<div class="line"><a id="l00067" name="l00067"></a><span class="lineno">   67</span><span class="comment"> *     - Each async operation is invoked via an `X.async_F(H)` method, to which one passes the handler `H` to invoke;</span></div>
<div class="line"><a id="l00068" name="l00068"></a><span class="lineno">   68</span><span class="comment"> *       and `H()` is called *exactly* once: when the async op completes (with or without error); or `X` is</span></div>
<div class="line"><a id="l00069" name="l00069"></a><span class="lineno">   69</span><span class="comment"> *       destroyed first (in which case an `operation_aborted`-like error code is emitted to `H()`).</span></div>
<div class="line"><a id="l00070" name="l00070"></a><span class="lineno">   70</span><span class="comment"> *     - If more than one `X.async_F()` is invoked, for a given `F` (e.g., 3 Blob_receiver::async_receive_blob()</span></div>
<div class="line"><a id="l00071" name="l00071"></a><span class="lineno">   71</span><span class="comment"> *       outstanding calls on one Blob_receiver), then they are queued inside X as needed, with each arriving result</span></div>
<div class="line"><a id="l00072" name="l00072"></a><span class="lineno">   72</span><span class="comment"> *       firing 1 handler, dequeuing it in FIFO order.</span></div>
<div class="line"><a id="l00073" name="l00073"></a><span class="lineno">   73</span><span class="comment"> *     - If a pipe-hosing error occurs, it is fed to all queued handlers (i.e., the internal queue is cleared)</span></div>
<div class="line"><a id="l00074" name="l00074"></a><span class="lineno">   74</span><span class="comment"> *       and any future-invoked-async-API-passed handlers also.</span></div>
<div class="line"><a id="l00075" name="l00075"></a><span class="lineno">   75</span><span class="comment"> *   - By contrast: The structured (struc::Channel) API is not at all boost.asio-like.</span></div>
<div class="line"><a id="l00076" name="l00076"></a><span class="lineno">   76</span><span class="comment"> *     - There are no `async_F()` async ops as such.  There is no FIFO-queueing of handlers.  Instead:</span></div>
<div class="line"><a id="l00077" name="l00077"></a><span class="lineno">   77</span><span class="comment"> *     - One registers events handlers for each type of event in which one is interested.  While it&#39;s possible</span></div>
<div class="line"><a id="l00078" name="l00078"></a><span class="lineno">   78</span><span class="comment"> *       to auto-unregister an event handler after it fires once, the general case is that an event handler</span></div>
<div class="line"><a id="l00079" name="l00079"></a><span class="lineno">   79</span><span class="comment"> *       registration is permanent until explicitly undone.</span></div>
<div class="line"><a id="l00080" name="l00080"></a><span class="lineno">   80</span><span class="comment"> *       - As a sub-case of this paradigm, the act of sending an out-message can be optionally paired with</span></div>
<div class="line"><a id="l00081" name="l00081"></a><span class="lineno">   81</span><span class="comment"> *         registering an event handler for when (and if) the other peer responds to that specific out-message</span></div>
<div class="line"><a id="l00082" name="l00082"></a><span class="lineno">   82</span><span class="comment"> *         with a response in-message.  Thus request/response semantics (while optional) are built-in.</span></div>
<div class="line"><a id="l00083" name="l00083"></a><span class="lineno">   83</span><span class="comment"> *       - As a sub-case of this paradigm, a single error handler is registered; if a pipe-hosing error occurs,</span></div>
<div class="line"><a id="l00084" name="l00084"></a><span class="lineno">   84</span><span class="comment"> *         then that handler is invoked just once -- as opposed to invoking all the other stored handlers with</span></div>
<div class="line"><a id="l00085" name="l00085"></a><span class="lineno">   85</span><span class="comment"> *         that same #Error_code.</span></div>
<div class="line"><a id="l00086" name="l00086"></a><span class="lineno">   86</span><span class="comment"> *</span></div>
<div class="line"><a id="l00087" name="l00087"></a><span class="lineno">   87</span><span class="comment"> * As for the *out-message* (sending) API: It is actually extremely similar to the unstructured layer&#39;s</span></div>
<div class="line"><a id="l00088" name="l00088"></a><span class="lineno">   88</span><span class="comment"> * already admirably simple API.  To recap:</span></div>
<div class="line"><a id="l00089" name="l00089"></a><span class="lineno">   89</span><span class="comment"> *   - If you want to send a message, you invoke send() or async_request().  Each is non-blocking *and* synchronous</span></div>
<div class="line"><a id="l00090" name="l00090"></a><span class="lineno">   90</span><span class="comment"> *     *yet* it cannot fail due to a would-block condition.  There is no asynchronous send op!</span></div>
<div class="line"><a id="l00091" name="l00091"></a><span class="lineno">   91</span><span class="comment"> *     - Alternatively use sync_request() which is a blocking, optionally subject to timeout, version of</span></div>
<div class="line"><a id="l00092" name="l00092"></a><span class="lineno">   92</span><span class="comment"> *       async_request().  It will block until a one-off response is received to the sent message</span></div>
<div class="line"><a id="l00093" name="l00093"></a><span class="lineno">   93</span><span class="comment"> *       (or timeout, or error) and return that response synchronously (if indeed successful).</span></div>
<div class="line"><a id="l00094" name="l00094"></a><span class="lineno">   94</span><span class="comment"> *     - Note that, while sync_request() is blocking, it can be used for very quick request-response exchanges;</span></div>
<div class="line"><a id="l00095" name="l00095"></a><span class="lineno">   95</span><span class="comment"> *       indeed that is its main use case.  For example, a memory-allocation op might contact the memory-allocating</span></div>
<div class="line"><a id="l00096" name="l00096"></a><span class="lineno">   96</span><span class="comment"> *       process and return once that process has acknowledged completing the alloc request.</span></div>
<div class="line"><a id="l00097" name="l00097"></a><span class="lineno">   97</span><span class="comment"> *   - Graceful closing is forwarded to the unstructured layer.  The Blob_sender, Native_handle_sender,</span></div>
<div class="line"><a id="l00098" name="l00098"></a><span class="lineno">   98</span><span class="comment"> *     transport::Channel async_end_sending() API is mimicked by simply passing-through to the owned #Owned_channel.</span></div>
<div class="line"><a id="l00099" name="l00099"></a><span class="lineno">   99</span><span class="comment"> *     - This features an asynchronous component.  Discussion omitted here; just see async_end_sending().</span></div>
<div class="line"><a id="l00100" name="l00100"></a><span class="lineno">  100</span><span class="comment"> *</span></div>
<div class="line"><a id="l00101" name="l00101"></a><span class="lineno">  101</span><span class="comment"> * However the out-message (sending) API adds an important (optional but highly encouraged) capability:</span></div>
<div class="line"><a id="l00102" name="l00102"></a><span class="lineno">  102</span><span class="comment"> *   - Every out-message can be allocated in SHM (shared memory) instead of heap; send() (et al) then transparently</span></div>
<div class="line"><a id="l00103" name="l00103"></a><span class="lineno">  103</span><span class="comment"> *     sends (copies into transport, on other side copies out of transport) a tiny *handle* to the message.</span></div>
<div class="line"><a id="l00104" name="l00104"></a><span class="lineno">  104</span><span class="comment"> *     - This is enabled, or disabled, for the entire `*this` via compile-time parameters and ctor args.</span></div>
<div class="line"><a id="l00105" name="l00105"></a><span class="lineno">  105</span><span class="comment"> *       After that the API is completely identical regardless of whether this full *zero-copy* mode is in use</span></div>
<div class="line"><a id="l00106" name="l00106"></a><span class="lineno">  106</span><span class="comment"> *       or not.</span></div>
<div class="line"><a id="l00107" name="l00107"></a><span class="lineno">  107</span><span class="comment"> *   - An out-message can be reused and sent again.  It can be modified in-between.  It would be practical to use</span></div>
<div class="line"><a id="l00108" name="l00108"></a><span class="lineno">  108</span><span class="comment"> *     this technique to store complex data structures integral to your application as opposed to a mere messaging</span></div>
<div class="line"><a id="l00109" name="l00109"></a><span class="lineno">  109</span><span class="comment"> *     focus.  This does not *require* the SHM-backed (zero-copy) mode, but it greatly improves performance</span></div>
<div class="line"><a id="l00110" name="l00110"></a><span class="lineno">  110</span><span class="comment"> *     when sharing with another process.</span></div>
<div class="line"><a id="l00111" name="l00111"></a><span class="lineno">  111</span><span class="comment"> *     - This is an alternative to storing a C++ data structure, such as a `vector` of `map`s of ..., in SHM</span></div>
<div class="line"><a id="l00112" name="l00112"></a><span class="lineno">  112</span><span class="comment"> *       manually and transmitting a handle manually.  Discussion of details of this is outside the scope</span></div>
<div class="line"><a id="l00113" name="l00113"></a><span class="lineno">  113</span><span class="comment"> *       here, but you should be aware that it&#39;s the alternative approach for structured-data storage in SHM</span></div>
<div class="line"><a id="l00114" name="l00114"></a><span class="lineno">  114</span><span class="comment"> *       and its IPC.  They each have their pros/cons.</span></div>
<div class="line"><a id="l00115" name="l00115"></a><span class="lineno">  115</span><span class="comment"> *</span></div>
<div class="line"><a id="l00116" name="l00116"></a><span class="lineno">  116</span><span class="comment"> * Long story short:</span></div>
<div class="line"><a id="l00117" name="l00117"></a><span class="lineno">  117</span><span class="comment"> *   - Sending is simple as in the unstructured layer.</span></div>
<div class="line"><a id="l00118" name="l00118"></a><span class="lineno">  118</span><span class="comment"> *     - However zero-copy backing of the structured message&#39;s serialization in SHM allows for far improved</span></div>
<div class="line"><a id="l00119" name="l00119"></a><span class="lineno">  119</span><span class="comment"> *       perf.</span></div>
<div class="line"><a id="l00120" name="l00120"></a><span class="lineno">  120</span><span class="comment"> *   - Receiving follows an event-handler-registration model, instead of the unstructured layer&#39;s preferred</span></div>
<div class="line"><a id="l00121" name="l00121"></a><span class="lineno">  121</span><span class="comment"> *     async-op-and-handler model (as inspired by boost.asio).</span></div>
<div class="line"><a id="l00122" name="l00122"></a><span class="lineno">  122</span><span class="comment"> *</span></div>
<div class="line"><a id="l00123" name="l00123"></a><span class="lineno">  123</span><span class="comment"> * ### Overview: How to use it, why to use it ###</span></div>
<div class="line"><a id="l00124" name="l00124"></a><span class="lineno">  124</span><span class="comment"> * How to use this thing?  Broadly speaking:</span></div>
<div class="line"><a id="l00125" name="l00125"></a><span class="lineno">  125</span><span class="comment"> *   -# One first establishes a channel connection (obtains a transport::Channel in PEER state).  See</span></div>
<div class="line"><a id="l00126" name="l00126"></a><span class="lineno">  126</span><span class="comment"> *      transport::Channel.  Attention: You will need a `sync_io`-pattern-peer-bearing transport::Channel</span></div>
<div class="line"><a id="l00127" name="l00127"></a><span class="lineno">  127</span><span class="comment"> *      (which is enforced at compile-time); formally `Owned_channel::S_IS_SYNC_IO_OBJ == true` is required.</span></div>
<div class="line"><a id="l00128" name="l00128"></a><span class="lineno">  128</span><span class="comment"> *      ipc::session emits such `Channel`s.  If you are manually assembling a `Channel` (or alias or</span></div>
<div class="line"><a id="l00129" name="l00129"></a><span class="lineno">  129</span><span class="comment"> *      data-less sub-class), then attaining fresh PEER-state peer objects of the `sync_io`-pattern variety</span></div>
<div class="line"><a id="l00130" name="l00130"></a><span class="lineno">  130</span><span class="comment"> *      should be equally easy.  In the case of Native_socket_stream specifically, you can perform</span></div>
<div class="line"><a id="l00131" name="l00131"></a><span class="lineno">  131</span><span class="comment"> *      `.sync_connect()` on a `sync_io`-pattern transport::sync_io::Native_socket_stream; on success bundle</span></div>
<div class="line"><a id="l00132" name="l00132"></a><span class="lineno">  132</span><span class="comment"> *      it into `Channel`.</span></div>
<div class="line"><a id="l00133" name="l00133"></a><span class="lineno">  133</span><span class="comment"> *   -# One selects the capnp message schema they wish to use.  In other words, what kinds of messages does</span></div>
<div class="line"><a id="l00134" name="l00134"></a><span class="lineno">  134</span><span class="comment"> *      one want to send?  This determines the choice of the #Msg_body template parameter.</span></div>
<div class="line"><a id="l00135" name="l00135"></a><span class="lineno">  135</span><span class="comment"> *   -# One selects a technique as to where/how out-messages (and consequently in-messages) will be stored in RAM:</span></div>
<div class="line"><a id="l00136" name="l00136"></a><span class="lineno">  136</span><span class="comment"> *      SHM (for full zero-copy performance) or heap (for zero-copy on either side of the low-level transport)..</span></div>
<div class="line"><a id="l00137" name="l00137"></a><span class="lineno">  137</span><span class="comment"> *      (Details omitted here, but for the sake of this brief recap let&#39;s consider this a formality.)</span></div>
<div class="line"><a id="l00138" name="l00138"></a><span class="lineno">  138</span><span class="comment"> *   -# One then constructs the struc::Channel, passing the transport::Channel (and the config from previous bullet</span></div>
<div class="line"><a id="l00139" name="l00139"></a><span class="lineno">  139</span><span class="comment"> *      point) into ctor -- which is moved-into the resulting `*this`.</span></div>
<div class="line"><a id="l00140" name="l00140"></a><span class="lineno">  140</span><span class="comment"> *   -# One then exchanges messages (and, if desired, native handles) with the matching struc::Channel on the</span></div>
<div class="line"><a id="l00141" name="l00141"></a><span class="lineno">  141</span><span class="comment"> *      other side via the `*this` transmission API.</span></div>
<div class="line"><a id="l00142" name="l00142"></a><span class="lineno">  142</span><span class="comment"> *   -# When `*this` is destroyed, so is the owned transport::Channel (and no earlier).</span></div>
<div class="line"><a id="l00143" name="l00143"></a><span class="lineno">  143</span><span class="comment"> *</span></div>
<div class="line"><a id="l00144" name="l00144"></a><span class="lineno">  144</span><span class="comment"> * So struc::Channel &quot;eats&quot; (via `std::move()`) a presumably fresh (no traffic exchanged) transport::Channel and all</span></div>
<div class="line"><a id="l00145" name="l00145"></a><span class="lineno">  145</span><span class="comment"> * further work on the transport::Channel is through struc::Channel.</span></div>
<div class="line"><a id="l00146" name="l00146"></a><span class="lineno">  146</span><span class="comment"> *</span></div>
<div class="line"><a id="l00147" name="l00147"></a><span class="lineno">  147</span><span class="comment"> * What does struc::Channel add, broadly speaking, that transport::Channel does not already have?  Why even bother?</span></div>
<div class="line"><a id="l00148" name="l00148"></a><span class="lineno">  148</span><span class="comment"> * Answer:</span></div>
<div class="line"><a id="l00149" name="l00149"></a><span class="lineno">  149</span><span class="comment"> *   - Firstly, each message no longer consists of an (optional unstructured binary blob, optional #Native_handle) pair.</span></div>
<div class="line"><a id="l00150" name="l00150"></a><span class="lineno">  150</span><span class="comment"> *     Instead if consists of a (structured capnp-schema-based message, optional #Native_handle) pair.</span></div>
<div class="line"><a id="l00151" name="l00151"></a><span class="lineno">  151</span><span class="comment"> *     In other words this class adds the (mandatory) ability to send *structured* data instead of mere</span></div>
<div class="line"><a id="l00152" name="l00152"></a><span class="lineno">  152</span><span class="comment"> *     binary blobs.  The schema language of choice is Cap&#39;n Proto (capnp), which allows for zero-copy perf</span></div>
<div class="line"><a id="l00153" name="l00153"></a><span class="lineno">  153</span><span class="comment"> *     *at least* until blobs enter the transport and after they exit the transport.</span></div>
<div class="line"><a id="l00154" name="l00154"></a><span class="lineno">  154</span><span class="comment"> *     - By choosing to use SHM-based serialization storage for out-messages, zero-copy perf can be extended</span></div>
<div class="line"><a id="l00155" name="l00155"></a><span class="lineno">  155</span><span class="comment"> *       end-to-end, meaning only a short handle is ever copied into the transport and out of it on the receiving</span></div>
<div class="line"><a id="l00156" name="l00156"></a><span class="lineno">  156</span><span class="comment"> *       side.</span></div>
<div class="line"><a id="l00157" name="l00157"></a><span class="lineno">  157</span><span class="comment"> *   - Secondly it establishes some convenient protocol notions on top of the basic message-boundary-respecting/reliable</span></div>
<div class="line"><a id="l00158" name="l00158"></a><span class="lineno">  158</span><span class="comment"> *     functionality of transport::Channel.</span></div>
<div class="line"><a id="l00159" name="l00159"></a><span class="lineno">  159</span><span class="comment"> *     - Message type (a/k/a #Msg_which): While #Msg_body can specify an essentially arbitrarily complex schema for</span></div>
<div class="line"><a id="l00160" name="l00160"></a><span class="lineno">  160</span><span class="comment"> *       what messages can be sent, with `*this` API being generally agnostic as to its details, it does establish</span></div>
<div class="line"><a id="l00161" name="l00161"></a><span class="lineno">  161</span><span class="comment"> *       one simple standard: The message schema #Msg_body *must* feature a top-level anonymous (capnp) *union*, with</span></div>
<div class="line"><a id="l00162" name="l00162"></a><span class="lineno">  162</span><span class="comment"> *       the &quot;which&quot; enumerator specifying the type of message that it is.  E.g., something approximating HTTP might</span></div>
<div class="line"><a id="l00163" name="l00163"></a><span class="lineno">  163</span><span class="comment"> *       have the top-level union specifying either a GET, POST, or CONNECT message type, with each one then featuring</span></div>
<div class="line"><a id="l00164" name="l00164"></a><span class="lineno">  164</span><span class="comment"> *       its own arbitrary capnp `struct` sub-schema, specifying what data come along with that type of message.</span></div>
<div class="line"><a id="l00165" name="l00165"></a><span class="lineno">  165</span><span class="comment"> *       - *Message type demuxing*: Based on this, one sets separate handlers for each individual value for</span></div>
<div class="line"><a id="l00166" name="l00166"></a><span class="lineno">  166</span><span class="comment"> *         an in-message&#39;s #Msg_which.</span></div>
<div class="line"><a id="l00167" name="l00167"></a><span class="lineno">  167</span><span class="comment"> *         - One-off demuxing: One can register the expectation for at most 1 message of a particular #Msg_which type.</span></div>
<div class="line"><a id="l00168" name="l00168"></a><span class="lineno">  168</span><span class="comment"> *           Then, when it is received, the expectation registration for that #Msg_which is auto-removed, as the</span></div>
<div class="line"><a id="l00169" name="l00169"></a><span class="lineno">  169</span><span class="comment"> *           user-supplied handler fires.</span></div>
<div class="line"><a id="l00170" name="l00170"></a><span class="lineno">  170</span><span class="comment"> *         - Open-ended demuxing: Alternatively one can set a permanent (unless explicitly unregistered later)</span></div>
<div class="line"><a id="l00171" name="l00171"></a><span class="lineno">  171</span><span class="comment"> *           expectation for a given #Msg_which.  Then the user-supplied handler will fire each time a matching</span></div>
<div class="line"><a id="l00172" name="l00172"></a><span class="lineno">  172</span><span class="comment"> *           in-message arrives.</span></div>
<div class="line"><a id="l00173" name="l00173"></a><span class="lineno">  173</span><span class="comment"> *         - (Queuing) Any messages that have no expect-this-`Msg_which` handler registered are queued inside `*this`.</span></div>
<div class="line"><a id="l00174" name="l00174"></a><span class="lineno">  174</span><span class="comment"> *           Registering a demux expectation later will immediately feed matching queued such in-messages, as if</span></div>
<div class="line"><a id="l00175" name="l00175"></a><span class="lineno">  175</span><span class="comment"> *           they&#39;d arrived right then.</span></div>
<div class="line"><a id="l00176" name="l00176"></a><span class="lineno">  176</span><span class="comment"> *     - *Request/response demuxing*: Any message one sends can optionally be specified to be expecting response</span></div>
<div class="line"><a id="l00177" name="l00177"></a><span class="lineno">  177</span><span class="comment"> *       in-message(s).  This is the alternative to #Msg_which-based demuxing.  This establishes a basic</span></div>
<div class="line"><a id="l00178" name="l00178"></a><span class="lineno">  178</span><span class="comment"> *       request/response paradigm.</span></div>
<div class="line"><a id="l00179" name="l00179"></a><span class="lineno">  179</span><span class="comment"> *       - One-off response demuxing: One can specify that the given out-message expects up to exactly 1 response.</span></div>
<div class="line"><a id="l00180" name="l00180"></a><span class="lineno">  180</span><span class="comment"> *       - Open-ended response demuxing: One can instead specify that any number of responses may arrive</span></div>
<div class="line"><a id="l00181" name="l00181"></a><span class="lineno">  181</span><span class="comment"> *         (until one explicitly unregisters this expectation).</span></div>
<div class="line"><a id="l00182" name="l00182"></a><span class="lineno">  182</span><span class="comment"> *       - (Note) If a response in-message arrives, while `*this` has no response expectation registered, it is</span></div>
<div class="line"><a id="l00183" name="l00183"></a><span class="lineno">  183</span><span class="comment"> *         an error.  However it is not necessarily a fatal error: There is a mechanism allowing the user</span></div>
<div class="line"><a id="l00184" name="l00184"></a><span class="lineno">  184</span><span class="comment"> *         to deal with this situation should it arise.  However a properly designed protocol would eliminate this</span></div>
<div class="line"><a id="l00185" name="l00185"></a><span class="lineno">  185</span><span class="comment"> *         possibility in practice (informally speaking).</span></div>
<div class="line"><a id="l00186" name="l00186"></a><span class="lineno">  186</span><span class="comment"> *     - A single full-duplex pipe: transport::Channel, one notes, can be a bundle of up to 2 full-duplex pipes (though</span></div>
<div class="line"><a id="l00187" name="l00187"></a><span class="lineno">  187</span><span class="comment"> *       at least 1 is of course required): one for blobs only; one for blob/`Native_handle` combos.</span></div>
<div class="line"><a id="l00188" name="l00188"></a><span class="lineno">  188</span><span class="comment"> *       The 2 do not interact; therefore if one were to use both in parallel, various questions arise as to how</span></div>
<div class="line"><a id="l00189" name="l00189"></a><span class="lineno">  189</span><span class="comment"> *       (and why!) to use this functionality.  struc::Channel elides these details completely and deals with</span></div>
<div class="line"><a id="l00190" name="l00190"></a><span class="lineno">  190</span><span class="comment"> *       them internally.  Bottom line:</span></div>
<div class="line"><a id="l00191" name="l00191"></a><span class="lineno">  191</span><span class="comment"> *       - struc::Channel API models a single full-duplex pipe capable of transmitting messages, each of which</span></div>
<div class="line"><a id="l00192" name="l00192"></a><span class="lineno">  192</span><span class="comment"> *         is *either* just a structured message *or* a structured message plus #Native_handle.  (The latter capability,</span></div>
<div class="line"><a id="l00193" name="l00193"></a><span class="lineno">  193</span><span class="comment"> *         naturally, is removed, if #Owned_channel lacks a handles pipe.)  Internally the transport::Channel pipes are</span></div>
<div class="line"><a id="l00194" name="l00194"></a><span class="lineno">  194</span><span class="comment"> *         leveraged in such a way as to maximize performance.</span></div>
<div class="line"><a id="l00195" name="l00195"></a><span class="lineno">  195</span><span class="comment"> *       - Messages arrive in the same order as they are sent (as determined by the order of send() (et al) calls on the</span></div>
<div class="line"><a id="l00196" name="l00196"></a><span class="lineno">  196</span><span class="comment"> *         sender `*this`).</span></div>
<div class="line"><a id="l00197" name="l00197"></a><span class="lineno">  197</span><span class="comment"> *         - If a message arrives that has no event handler registered, then it is queued inside `*this`, as explained</span></div>
<div class="line"><a id="l00198" name="l00198"></a><span class="lineno">  198</span><span class="comment"> *           above.  They are queued, and therefore popped if/when a handler is registered, in the same order as</span></div>
<div class="line"><a id="l00199" name="l00199"></a><span class="lineno">  199</span><span class="comment"> *           they arrived.</span></div>
<div class="line"><a id="l00200" name="l00200"></a><span class="lineno">  200</span><span class="comment"> *         - Suppose message with sequence # 5 has arrived but had to be queued due to lacking a registered handler.</span></div>
<div class="line"><a id="l00201" name="l00201"></a><span class="lineno">  201</span><span class="comment"> *           Suppose message with sequence # 6 has arrived and *does* have a registered handler.  Message 6 will</span></div>
<div class="line"><a id="l00202" name="l00202"></a><span class="lineno">  202</span><span class="comment"> *           then be emitted to the user; in other words the act of being queued does not preclude the emission of</span></div>
<div class="line"><a id="l00203" name="l00203"></a><span class="lineno">  203</span><span class="comment"> *           subsequent messages.</span></div>
<div class="line"><a id="l00204" name="l00204"></a><span class="lineno">  204</span><span class="comment"> *     - Thirdly, there are some (mandatory) safety features.  These are almost completely hidden from the user in</span></div>
<div class="line"><a id="l00205" name="l00205"></a><span class="lineno">  205</span><span class="comment"> *       regular operation.  To the extent they are not, it has to do with the *log-in* feature.  This is discussed</span></div>
<div class="line"><a id="l00206" name="l00206"></a><span class="lineno">  206</span><span class="comment"> *       separately below.  Typically one need not worry about it.</span></div>
<div class="line"><a id="l00207" name="l00207"></a><span class="lineno">  207</span><span class="comment"> *</span></div>
<div class="line"><a id="l00208" name="l00208"></a><span class="lineno">  208</span><span class="comment"> * ### How to use it (deep-dive) (log-in excluded) ###</span></div>
<div class="line"><a id="l00209" name="l00209"></a><span class="lineno">  209</span><span class="comment"> * Naturally there are two directions of transmission, sending out-messages and receiving in-messages.  About the</span></div>
<div class="line"><a id="l00210" name="l00210"></a><span class="lineno">  210</span><span class="comment"> * former first:</span></div>
<div class="line"><a id="l00211" name="l00211"></a><span class="lineno">  211</span><span class="comment"> *</span></div>
<div class="line"><a id="l00212" name="l00212"></a><span class="lineno">  212</span><span class="comment"> * To transmit an out-message:</span></div>
<div class="line"><a id="l00213" name="l00213"></a><span class="lineno">  213</span><span class="comment"> *   - Call create_msg(); this yields a cheaply-`move()`able out-message:</span></div>
<div class="line"><a id="l00214" name="l00214"></a><span class="lineno">  214</span><span class="comment"> *     #Msg_out.  (See Msg_out doc header for formal public API.)  You may also construct this</span></div>
<div class="line"><a id="l00215" name="l00215"></a><span class="lineno">  215</span><span class="comment"> *     directly -- even without a struc::Channel in existence at all; create_msg() merely helps by</span></div>
<div class="line"><a id="l00216" name="l00216"></a><span class="lineno">  216</span><span class="comment"> *     supplying the serialize/deserialize parameters (a/k/a builder/reader config) for you.</span></div>
<div class="line"><a id="l00217" name="l00217"></a><span class="lineno">  217</span><span class="comment"> *   - Fill out its contents: `M-&gt;body_root()` is a `Msg_body::Builder*`, where #Msg_body is determined by your</span></div>
<div class="line"><a id="l00218" name="l00218"></a><span class="lineno">  218</span><span class="comment"> *     choice of schema (`Message_body` template param); and `Msg_body::Builder` is the capnp-generated</span></div>
<div class="line"><a id="l00219" name="l00219"></a><span class="lineno">  219</span><span class="comment"> *     mutating API.  For example: `M-&gt;body_root()-&gt;initCoolRequest().setCoolField(57);`</span></div>
<div class="line"><a id="l00220" name="l00220"></a><span class="lineno">  220</span><span class="comment"> *     - sets the message type to `Msg_body::Which::COOL_REQUEST` and initializes a blank `CoolRequest` capnp-struct;</span></div>
<div class="line"><a id="l00221" name="l00221"></a><span class="lineno">  221</span><span class="comment"> *     - mutates the field `coolField` -- presumably an integer of some kind in this example -- to equal 57.</span></div>
<div class="line"><a id="l00222" name="l00222"></a><span class="lineno">  222</span><span class="comment"> *   - Send it: `send(M)` or `async_request(M)`.  Each is non-blocking, synchronous, and cannot would-block.</span></div>
<div class="line"><a id="l00223" name="l00223"></a><span class="lineno">  223</span><span class="comment"> *     - If `M` is a response to some in-message `I`, use `send/async_request(M, I, ...)`.  Otherwise use</span></div>
<div class="line"><a id="l00224" name="l00224"></a><span class="lineno">  224</span><span class="comment"> *       `send/async_request(M, nullptr, ...)`.</span></div>
<div class="line"><a id="l00225" name="l00225"></a><span class="lineno">  225</span><span class="comment"> *     - If you expect *response* message(s) to `M`, use `async_request(M, ..., &amp;id, H)`, where:</span></div>
<div class="line"><a id="l00226" name="l00226"></a><span class="lineno">  226</span><span class="comment"> *       - Set `&amp;id` to `nullptr` if one expects at most 1 response to `M`; otherwise non-null.</span></div>
<div class="line"><a id="l00227" name="l00227"></a><span class="lineno">  227</span><span class="comment"> *         - In the latter case optionally use `undo_expect_responses(id)` to indicate no further responses</span></div>
<div class="line"><a id="l00228" name="l00228"></a><span class="lineno">  228</span><span class="comment"> *           to the out-message instance sent by that async_request() call are expected.</span></div>
<div class="line"><a id="l00229" name="l00229"></a><span class="lineno">  229</span><span class="comment"> *       - `H` is the handler for the reponse(s); `H(I)` shall be invoked, where `I` is the response in-message.</span></div>
<div class="line"><a id="l00230" name="l00230"></a><span class="lineno">  230</span><span class="comment"> *   - Alternatively to async_request(): `sync_request(M)`.  This is similar, but instead of returning it</span></div>
<div class="line"><a id="l00231" name="l00231"></a><span class="lineno">  231</span><span class="comment"> *     awaits the response and returns that response once received.</span></div>
<div class="line"><a id="l00232" name="l00232"></a><span class="lineno">  232</span><span class="comment"> *     Note that by definition such a request is one-off (exactly 1 response is expected).  sync_request() can</span></div>
<div class="line"><a id="l00233" name="l00233"></a><span class="lineno">  233</span><span class="comment"> *     optionally specify a timeout.</span></div>
<div class="line"><a id="l00234" name="l00234"></a><span class="lineno">  234</span><span class="comment"> *   - Note: See async_end_sending() doc header.  TL;DR: You should call this when done using `*this`; then destroy</span></div>
<div class="line"><a id="l00235" name="l00235"></a><span class="lineno">  235</span><span class="comment"> *     `*this` once the async-handler you passed to async_end_sending() has fired.</span></div>
<div class="line"><a id="l00236" name="l00236"></a><span class="lineno">  236</span><span class="comment"> *</span></div>
<div class="line"><a id="l00237" name="l00237"></a><span class="lineno">  237</span><span class="comment"> * As usual, the incoming direction is somewhat more complex.  It is also different from lower-level APIs</span></div>
<div class="line"><a id="l00238" name="l00238"></a><span class="lineno">  238</span><span class="comment"> * such as boost.asio sockets and our various `Blob_sender`s and the like.</span></div>
<div class="line"><a id="l00239" name="l00239"></a><span class="lineno">  239</span><span class="comment"> *</span></div>
<div class="line"><a id="l00240" name="l00240"></a><span class="lineno">  240</span><span class="comment"> * Internally, all in-messages that do arrive on the &quot;wire&quot; are received immediately; each in-message at that point</span></div>
<div class="line"><a id="l00241" name="l00241"></a><span class="lineno">  241</span><span class="comment"> * is then handled in exactly one of the following ways.  (Here we do not discuss pipe-hosing errors, yet.)</span></div>
<div class="line"><a id="l00242" name="l00242"></a><span class="lineno">  242</span><span class="comment"> * A given in-message `I` is handled thus:</span></div>
<div class="line"><a id="l00243" name="l00243"></a><span class="lineno">  243</span><span class="comment"> *   - If `I` is not a response to an earlier out-message `M`:</span></div>
<div class="line"><a id="l00244" name="l00244"></a><span class="lineno">  244</span><span class="comment"> *     - If `I` is being expected via an earlier expect_msg() or expect_msgs() call: *Emit* `I` to that user handler.</span></div>
<div class="line"><a id="l00245" name="l00245"></a><span class="lineno">  245</span><span class="comment"> *     - Else: queue it inside `*this` silently.</span></div>
<div class="line"><a id="l00246" name="l00246"></a><span class="lineno">  246</span><span class="comment"> *   - Else:</span></div>
<div class="line"><a id="l00247" name="l00247"></a><span class="lineno">  247</span><span class="comment"> *     - If `I` is being expected via a response-expectation, as registered in async_request() or</span></div>
<div class="line"><a id="l00248" name="l00248"></a><span class="lineno">  248</span><span class="comment"> *       sync_request() (see above):</span></div>
<div class="line"><a id="l00249" name="l00249"></a><span class="lineno">  249</span><span class="comment"> *       *Emit* `I` to that user handler, or return it via sync_request() synchronously (whichever applies).</span></div>
<div class="line"><a id="l00250" name="l00250"></a><span class="lineno">  250</span><span class="comment"> *     - Else: it is a non-pipe hosing error condition.  While you should (informally speaking) avoid this, if</span></div>
<div class="line"><a id="l00251" name="l00251"></a><span class="lineno">  251</span><span class="comment"> *       it does occur, you can handle it as you see fit.  See set_unexpected_response_handler().</span></div>
<div class="line"><a id="l00252" name="l00252"></a><span class="lineno">  252</span><span class="comment"> *       See also set_remote_unexpected_response_handler().  Spoiler alert: This condition is emitted on both</span></div>
<div class="line"><a id="l00253" name="l00253"></a><span class="lineno">  253</span><span class="comment"> *       sides: locally, indicating an unexpected response arrived; and remotely, indicating that side *issued*</span></div>
<div class="line"><a id="l00254" name="l00254"></a><span class="lineno">  254</span><span class="comment"> *       an unexpected response.</span></div>
<div class="line"><a id="l00255" name="l00255"></a><span class="lineno">  255</span><span class="comment"> *</span></div>
<div class="line"><a id="l00256" name="l00256"></a><span class="lineno">  256</span><span class="comment"> * Hence there are exactly 3 ways to register a handler for in-messages.</span></div>
<div class="line"><a id="l00257" name="l00257"></a><span class="lineno">  257</span><span class="comment"> *   - Call expect_msg() or expect_msgs() to expect a particular type of *unsolicited* (non-response) message.</span></div>
<div class="line"><a id="l00258" name="l00258"></a><span class="lineno">  258</span><span class="comment"> *     expect_msg() indicates up to 1 such message shall be expected; expect_msgs() indicates 0+ such messages,</span></div>
<div class="line"><a id="l00259" name="l00259"></a><span class="lineno">  259</span><span class="comment"> *     until undo_expect_msgs().</span></div>
<div class="line"><a id="l00260" name="l00260"></a><span class="lineno">  260</span><span class="comment"> *     - If expect_msg() or expect_msgs() is invoked, and matching message(s) are queued inside `*this` (per above)</span></div>
<div class="line"><a id="l00261" name="l00261"></a><span class="lineno">  261</span><span class="comment"> *       at that time, `*this` behaves as-if those messages had just arrived.  I.e., they are immediately</span></div>
<div class="line"><a id="l00262" name="l00262"></a><span class="lineno">  262</span><span class="comment"> *       *emitted*.</span></div>
<div class="line"><a id="l00263" name="l00263"></a><span class="lineno">  263</span><span class="comment"> *   - Call async_request() to expect a response to a particular out-message.</span></div>
<div class="line"><a id="l00264" name="l00264"></a><span class="lineno">  264</span><span class="comment"> *   - Call sync_request() to send request and synchronously await one-off response to that particular out-message.</span></div>
<div class="line"><a id="l00265" name="l00265"></a><span class="lineno">  265</span><span class="comment"> *</span></div>
<div class="line"><a id="l00266" name="l00266"></a><span class="lineno">  266</span><span class="comment"> * Example:</span></div>
<div class="line"><a id="l00267" name="l00267"></a><span class="lineno">  267</span><span class="comment"> *   - I am a server, and I expect GET and POST messages.  I invoke `expect_msgs(Msg_which_in::GET_REQ, handle_get_req)`</span></div>
<div class="line"><a id="l00268" name="l00268"></a><span class="lineno">  268</span><span class="comment"> *     and `expect_msgs(Msg_which::POST_REQ, handle_post_req)`.  `handle_get_req(x)` shall be invoked for each</span></div>
<div class="line"><a id="l00269" name="l00269"></a><span class="lineno">  269</span><span class="comment"> *     incoming GET_REQ `x` and similarly for the POSTs.</span></div>
<div class="line"><a id="l00270" name="l00270"></a><span class="lineno">  270</span><span class="comment"> *   - I am a client, and I issue GET and POST messages.  I invoke `async_request(x, ..., nullptr, handle_get_rsp)`</span></div>
<div class="line"><a id="l00271" name="l00271"></a><span class="lineno">  271</span><span class="comment"> *     for a GET and `async_request(y, ..., nullptr, handle_post_rsp)`, where earlier one did:</span></div>
<div class="line"><a id="l00272" name="l00272"></a><span class="lineno">  272</span><span class="comment"> *     - `x = ....create_msg()`; `x-&gt;body_root()-&gt;initGetReq().set{Url|HostHeader}(...)`;</span></div>
<div class="line"><a id="l00273" name="l00273"></a><span class="lineno">  273</span><span class="comment"> *     - `y = ....create_msg()`; `y-&gt;body_root()-&gt;initPostReq().set{Url|HostHeader|PostBody}(...)`.</span></div>
<div class="line"><a id="l00274" name="l00274"></a><span class="lineno">  274</span><span class="comment"> *</span></div>
<div class="line"><a id="l00275" name="l00275"></a><span class="lineno">  275</span><span class="comment"> * Last but not least: How does one read the contents of an incoming message?  For both paths -- unsolicited message</span></div>
<div class="line"><a id="l00276" name="l00276"></a><span class="lineno">  276</span><span class="comment"> * expectation via expect_msg()/expect_msgs() + response message expectation via async_request() alike -- the</span></div>
<div class="line"><a id="l00277" name="l00277"></a><span class="lineno">  277</span><span class="comment"> * user-provided handler shall be of the form: `H(I&amp;&amp;)`, where `I` is a #Msg_in_ptr, a ref-counted handle to a new</span></div>
<div class="line"><a id="l00278" name="l00278"></a><span class="lineno">  278</span><span class="comment"> * in-message.  (See Msg_in doc header for the formal public API.)  Note the `&amp;&amp;`: it is an rvalue reference</span></div>
<div class="line"><a id="l00279" name="l00279"></a><span class="lineno">  279</span><span class="comment"> * to the `shared_ptr`, rather than a `const &amp;`, in case you&#39;d like to `move()` it somewhere for perf instead of</span></div>
<div class="line"><a id="l00280" name="l00280"></a><span class="lineno">  280</span><span class="comment"> * ref-counting increment/decrement.</span></div>
<div class="line"><a id="l00281" name="l00281"></a><span class="lineno">  281</span><span class="comment"> *   - `I-&gt;body_root()` is a `const Msg_body::Reader&amp;`, where #Msg_body is as explained earlier, and</span></div>
<div class="line"><a id="l00282" name="l00282"></a><span class="lineno">  282</span><span class="comment"> *     `Msg_body::Reader` is the capnp-generated accessor API.</span></div>
<div class="line"><a id="l00283" name="l00283"></a><span class="lineno">  283</span><span class="comment"> *     For example: `I-&gt;body_root().getCoolRequest().getCoolField()` shall equal 57 on the other end, following</span></div>
<div class="line"><a id="l00284" name="l00284"></a><span class="lineno">  284</span><span class="comment"> *     the earlier out-message example.</span></div>
<div class="line"><a id="l00285" name="l00285"></a><span class="lineno">  285</span><span class="comment"> *   - In the case of unsolicited messages: `I-&gt;body_root().which()` shall equal the #Msg_which_in passed</span></div>
<div class="line"><a id="l00286" name="l00286"></a><span class="lineno">  286</span><span class="comment"> *     to expect_msg() or expect_msgs().  Therefore one can perform `I-&gt;body_root().getCoolRequest()` without</span></div>
<div class="line"><a id="l00287" name="l00287"></a><span class="lineno">  287</span><span class="comment"> *     fear it&#39;s not actually a `COOL_REQUEST` (which would yield a capnp exception).</span></div>
<div class="line"><a id="l00288" name="l00288"></a><span class="lineno">  288</span><span class="comment"> *   - In the case of response messages: `I-&gt;body_root().which()` can be anything (i.e., `*this` will not enforce</span></div>
<div class="line"><a id="l00289" name="l00289"></a><span class="lineno">  289</span><span class="comment"> *     anything about it).  It is up to you to design that protocol.</span></div>
<div class="line"><a id="l00290" name="l00290"></a><span class="lineno">  290</span><span class="comment"> *     - I (ygoldfel) considered enforcing a #Msg_which_in expectation for responses, to be supplied with</span></div>
<div class="line"><a id="l00291" name="l00291"></a><span class="lineno">  291</span><span class="comment"> *       async_request().  However it seemed too restrictive to mandate it.</span></div>
<div class="line"><a id="l00292" name="l00292"></a><span class="lineno">  292</span><span class="comment"> * @todo Consider adding the *optional* expectation of a particular #Msg_which_in when registering expected</span></div>
<div class="line"><a id="l00293" name="l00293"></a><span class="lineno">  293</span><span class="comment"> * responses in struc::Channel::async_request().</span></div>
<div class="line"><a id="l00294" name="l00294"></a><span class="lineno">  294</span><span class="comment"> *</span></div>
<div class="line"><a id="l00295" name="l00295"></a><span class="lineno">  295</span><span class="comment"> * ### Thread safety; handler invocation semantics ###</span></div>
<div class="line"><a id="l00296" name="l00296"></a><span class="lineno">  296</span><span class="comment"> * In-message handlers, and all other handlers (including those from start(), set_unexpected_response_handler(),</span></div>
<div class="line"><a id="l00297" name="l00297"></a><span class="lineno">  297</span><span class="comment"> * set_remote_unexpected_response_handler(), async_end_sending()), are invoked from an unspecified thread guaranteed not</span></div>
<div class="line"><a id="l00298" name="l00298"></a><span class="lineno">  298</span><span class="comment"> * to be among the user invoking threads.  No 2 such handlers shall be invoked concurrently to each other.</span></div>
<div class="line"><a id="l00299" name="l00299"></a><span class="lineno">  299</span><span class="comment"> *</span></div>
<div class="line"><a id="l00300" name="l00300"></a><span class="lineno">  300</span><span class="comment"> * Messages are emitted in the order received, except reordered as required by the queueing of not-yet-expected</span></div>
<div class="line"><a id="l00301" name="l00301"></a><span class="lineno">  301</span><span class="comment"> * unsolicited messages (as explained earlier).</span></div>
<div class="line"><a id="l00302" name="l00302"></a><span class="lineno">  302</span><span class="comment"> *</span></div>
<div class="line"><a id="l00303" name="l00303"></a><span class="lineno">  303</span><span class="comment"> * Attention!  Regarding general thread safety: A given `*this` features stronger safety than most other APIs:</span></div>
<div class="line"><a id="l00304" name="l00304"></a><span class="lineno">  304</span><span class="comment"> *   - **It is safe** to invoke a method concurrently with another method call (to the same or other API)</span></div>
<div class="line"><a id="l00305" name="l00305"></a><span class="lineno">  305</span><span class="comment"> *     on the same `*this`.</span></div>
<div class="line"><a id="l00306" name="l00306"></a><span class="lineno">  306</span><span class="comment"> *</span></div>
<div class="line"><a id="l00307" name="l00307"></a><span class="lineno">  307</span><span class="comment"> * You *may* call `*this` APIs directly from any in-message handler or other handler.</span></div>
<div class="line"><a id="l00308" name="l00308"></a><span class="lineno">  308</span><span class="comment"> * Exception: You may *not* invoke sync_request() (or any other `sync_*()` that may be added over time)</span></div>
<div class="line"><a id="l00309" name="l00309"></a><span class="lineno">  309</span><span class="comment"> * from an in-message handler or other handler.  Doing so can disrupt the timeliness of delivering</span></div>
<div class="line"><a id="l00310" name="l00310"></a><span class="lineno">  310</span><span class="comment"> * other async results.</span></div>
<div class="line"><a id="l00311" name="l00311"></a><span class="lineno">  311</span><span class="comment"> *</span></div>
<div class="line"><a id="l00312" name="l00312"></a><span class="lineno">  312</span><span class="comment"> * Informal recommendation:</span></div>
<div class="line"><a id="l00313" name="l00313"></a><span class="lineno">  313</span><span class="comment"> * You should off-load most or all handling of in-messages onto your own thread(s) (such as via boost.asio</span></div>
<div class="line"><a id="l00314" name="l00314"></a><span class="lineno">  314</span><span class="comment"> * `post()` or the flow.async infrastructure).  For example, suppose your program has some main worker thread U,</span></div>
<div class="line"><a id="l00315" name="l00315"></a><span class="lineno">  315</span><span class="comment"> * implemented as a `flow::async::Single_thread_task_loop U`.  Then, e.g.:</span></div>
<div class="line"><a id="l00316" name="l00316"></a><span class="lineno">  316</span><span class="comment"> *   - In thread U: `async_request(M, false, H)`:</span></div>
<div class="line"><a id="l00317" name="l00317"></a><span class="lineno">  317</span><span class="comment"> *     sends `M`; async-calls `H(I)` when response `I` to `M` arrives.</span></div>
<div class="line"><a id="l00318" name="l00318"></a><span class="lineno">  318</span><span class="comment"> *   - In (unspecified thread): `H(I)` fires.  Your `H()` body:</span></div>
<div class="line"><a id="l00319" name="l00319"></a><span class="lineno">  319</span><span class="comment"> *     `U.post([I = std::move(I)]() { handle_i(std::move(I)); })`.</span></div>
<div class="line"><a id="l00320" name="l00320"></a><span class="lineno">  320</span><span class="comment"> *   - Actual handling of `I` occurs in your `void handle_i(...::Msg_in_ptr&amp;&amp;) { ... }`.</span></div>
<div class="line"><a id="l00321" name="l00321"></a><span class="lineno">  321</span><span class="comment"> *     `handle_i(){}` can be written with the assumption execution is back in thread U, same as the async_request()</span></div>
<div class="line"><a id="l00322" name="l00322"></a><span class="lineno">  322</span><span class="comment"> *     call that triggered all this (asynchronously).</span></div>
<div class="line"><a id="l00323" name="l00323"></a><span class="lineno">  323</span><span class="comment"> *</span></div>
<div class="line"><a id="l00324" name="l00324"></a><span class="lineno">  324</span><span class="comment"> * This is *not* a requirement.  It is entirely conceivable one would want to piggy-back onto our internal</span></div>
<div class="line"><a id="l00325" name="l00325"></a><span class="lineno">  325</span><span class="comment"> * unspecified thread (or threads -- formally speaking -- but the guarantee is handlers are called</span></div>
<div class="line"><a id="l00326" name="l00326"></a><span class="lineno">  326</span><span class="comment"> * non-concurrently, so in most senses one can treat it as a single thread).  However please be mindful:</span></div>
<div class="line"><a id="l00327" name="l00327"></a><span class="lineno">  327</span><span class="comment"> *   - If your handler code is &quot;heavy,&quot; then you may slow down internal transport::Channel and struc::Channel</span></div>
<div class="line"><a id="l00328" name="l00328"></a><span class="lineno">  328</span><span class="comment"> *     processing on a number of layers (though, only relevant to `*this`).</span></div>
<div class="line"><a id="l00329" name="l00329"></a><span class="lineno">  329</span><span class="comment"> *</span></div>
<div class="line"><a id="l00330" name="l00330"></a><span class="lineno">  330</span><span class="comment"> * ### Pipe-hosing error semantics ###</span></div>
<div class="line"><a id="l00331" name="l00331"></a><span class="lineno">  331</span><span class="comment"> * The underlying transport::Channel, which every struc::Channel takes over in the first place at construction,</span></div>
<div class="line"><a id="l00332" name="l00332"></a><span class="lineno">  332</span><span class="comment"> * can fail -- encounter a pipe-hosing error.  Briefly speaking, a transport::Channel out-pipe can -- depending</span></div>
<div class="line"><a id="l00333" name="l00333"></a><span class="lineno">  333</span><span class="comment"> * on the actual low-level transport involved -- be hosed while the in-pipe(s) remain unaffected; and indeed when</span></div>
<div class="line"><a id="l00334" name="l00334"></a><span class="lineno">  334</span><span class="comment"> * a transport::Channel internally consists of 2 bidirectional pipes, it is even possible for 1 out-pipe to be hosed,</span></div>
<div class="line"><a id="l00335" name="l00335"></a><span class="lineno">  335</span><span class="comment"> * while the other is not.  (The same holds of in-pipes.)  However, these details strongly depend on the actual</span></div>
<div class="line"><a id="l00336" name="l00336"></a><span class="lineno">  336</span><span class="comment"> * low-level transports involved.  To simplify error handling, these details are hidden away and normalized to</span></div>
<div class="line"><a id="l00337" name="l00337"></a><span class="lineno">  337</span><span class="comment"> * the following straightforward behavior.</span></div>
<div class="line"><a id="l00338" name="l00338"></a><span class="lineno">  338</span><span class="comment"> *</span></div>
<div class="line"><a id="l00339" name="l00339"></a><span class="lineno">  339</span><span class="comment"> * As noted before, struc::Channel models a single bidirectional full-duplex pipe of discrete messages.</span></div>
<div class="line"><a id="l00340" name="l00340"></a><span class="lineno">  340</span><span class="comment"> * The out-pipe is controlled simply: call send(), async_request(), or sync_request() to send a message, synchronously,</span></div>
<div class="line"><a id="l00341" name="l00341"></a><span class="lineno">  341</span><span class="comment"> * non-blockingly (if not sync_request()).</span></div>
<div class="line"><a id="l00342" name="l00342"></a><span class="lineno">  342</span><span class="comment"> * The in-pipe takes in all messages as soon as they arrive on the transport::Channel &quot;wire&quot;; they may be queued inside</span></div>
<div class="line"><a id="l00343" name="l00343"></a><span class="lineno">  343</span><span class="comment"> * or immediately (or later) emitted, but this is not relevant to error handling.</span></div>
<div class="line"><a id="l00344" name="l00344"></a><span class="lineno">  344</span><span class="comment"> *</span></div>
<div class="line"><a id="l00345" name="l00345"></a><span class="lineno">  345</span><span class="comment"> * The entire bidirectional pipe is either not-hosed, or it is hosed (forever).  A pipe-hosing condition,</span></div>
<div class="line"><a id="l00346" name="l00346"></a><span class="lineno">  346</span><span class="comment"> * indicated by a truthy #Error_code, occurs (if it occurs at all) exactly once.  (Note: Receiving the</span></div>
<div class="line"><a id="l00347" name="l00347"></a><span class="lineno">  347</span><span class="comment"> * `transport::Channel`-level graceful-close message -- transport::error::Code:: S_RECEIVES_FINISHED_CANNOT_RECEIVE --</span></div>
<div class="line"><a id="l00348" name="l00348"></a><span class="lineno">  348</span><span class="comment"> * is not &quot;special&quot; -- it is also a pipe-hosing error.)  When it occurs, it is immediately emitted to the</span></div>
<div class="line"><a id="l00349" name="l00349"></a><span class="lineno">  349</span><span class="comment"> * `*this` user.  There are 2 possible ways this can occur (again: only 1 of these can occur per `*this`):</span></div>
<div class="line"><a id="l00350" name="l00350"></a><span class="lineno">  350</span><span class="comment"> *   - Triggered by send(), async_request(), or sync_request(): Then that method shall emit the truthy #Error_code</span></div>
<div class="line"><a id="l00351" name="l00351"></a><span class="lineno">  351</span><span class="comment"> *     directly/synchronously via out-arg or exception.</span></div>
<div class="line"><a id="l00352" name="l00352"></a><span class="lineno">  352</span><span class="comment"> *   - Triggered spuriously in the background via incoming-direction processing: Then it shall be emitted via</span></div>
<div class="line"><a id="l00353" name="l00353"></a><span class="lineno">  353</span><span class="comment"> *     the on-error handler registered by the user.  (If this occurs during sync_request(), then it shall be</span></div>
<div class="line"><a id="l00354" name="l00354"></a><span class="lineno">  354</span><span class="comment"> *     emitted via sync_request(), not via on-error handler.)</span></div>
<div class="line"><a id="l00355" name="l00355"></a><span class="lineno">  355</span><span class="comment"> *     - To receive any in-messages, you must call start() which takes the mandatory on-error handler as arg.</span></div>
<div class="line"><a id="l00356" name="l00356"></a><span class="lineno">  356</span><span class="comment"> *       Until then, any lower-level in-traffic shall be safely queued inside the #Owned_channel.  Still, it is</span></div>
<div class="line"><a id="l00357" name="l00357"></a><span class="lineno">  357</span><span class="comment"> *       best to call start() early, to avoid RAM backup and such (informally speaking).</span></div>
<div class="line"><a id="l00358" name="l00358"></a><span class="lineno">  358</span><span class="comment"> *</span></div>
<div class="line"><a id="l00359" name="l00359"></a><span class="lineno">  359</span><span class="comment"> * After the pipe-hosing error is emitted, via exactly 1 of the above methods, further API calls on `*this` shall</span></div>
<div class="line"><a id="l00360" name="l00360"></a><span class="lineno">  360</span><span class="comment"> * no-op and return `false` or a null value.</span></div>
<div class="line"><a id="l00361" name="l00361"></a><span class="lineno">  361</span><span class="comment"> *</span></div>
<div class="line"><a id="l00362" name="l00362"></a><span class="lineno">  362</span><span class="comment"> * Lastly, there is async_end_sending().  See its doc header.  TL;DR: Although the pipe is hosed at the</span></div>
<div class="line"><a id="l00363" name="l00363"></a><span class="lineno">  363</span><span class="comment"> * struc::Channel level once a pipe-hosing #Error_code is emitted, it is still a good idea to execute</span></div>
<div class="line"><a id="l00364" name="l00364"></a><span class="lineno">  364</span><span class="comment"> * async_end_sending() and only destroy `*this` once the async-handler passed to it has fired.  (Though, if</span></div>
<div class="line"><a id="l00365" name="l00365"></a><span class="lineno">  365</span><span class="comment"> * send() (et al) emitted the truthy #Error_code, there is no point: async_end_sending() will no-op.)</span></div>
<div class="line"><a id="l00366" name="l00366"></a><span class="lineno">  366</span><span class="comment"> *</span></div>
<div class="line"><a id="l00367" name="l00367"></a><span class="lineno">  367</span><span class="comment"> * Informal recommendations:</span></div>
<div class="line"><a id="l00368" name="l00368"></a><span class="lineno">  368</span><span class="comment"> *   - Recall that we recommend any event handling, from within an in-message handler or any other handler,</span></div>
<div class="line"><a id="l00369" name="l00369"></a><span class="lineno">  369</span><span class="comment"> *     be immediately off-loaded onto a user worker thread.  (In particular you may not call `*this` APIs from these</span></div>
<div class="line"><a id="l00370" name="l00370"></a><span class="lineno">  370</span><span class="comment"> *     handlers.)</span></div>
<div class="line"><a id="l00371" name="l00371"></a><span class="lineno">  371</span><span class="comment"> *   - When such a user-thread handler, or other user-thread function, detects the emitted truthy #Error_code</span></div>
<div class="line"><a id="l00372" name="l00372"></a><span class="lineno">  372</span><span class="comment"> *     (from on-error handler, or via send(), async_request(), or sync_request() emitting it synchronously), mark</span></div>
<div class="line"><a id="l00373" name="l00373"></a><span class="lineno">  373</span><span class="comment"> *     `*this`, somehow, as hosed (e.g., via a flag or saved truthy #Error_code).</span></div>
<div class="line"><a id="l00374" name="l00374"></a><span class="lineno">  374</span><span class="comment"> *   - When about to do work on `*this`, check that flag or mark, so as to be aware `*this` is hosed and shutting</span></div>
<div class="line"><a id="l00375" name="l00375"></a><span class="lineno">  375</span><span class="comment"> *     down -- and no-op instead of trying to call whatever API.  Though, it may be viable to simply count on</span></div>
<div class="line"><a id="l00376" name="l00376"></a><span class="lineno">  376</span><span class="comment"> *     the fact `*this` APIs shall all (except async_end_sending()) no-op and return `false` or null in that case</span></div>
<div class="line"><a id="l00377" name="l00377"></a><span class="lineno">  377</span><span class="comment"> *     anyway.</span></div>
<div class="line"><a id="l00378" name="l00378"></a><span class="lineno">  378</span><span class="comment"> *   - Lastly, recommend then calling `async_end_sending(F)`; and in `F()` destroy `*this` finally.</span></div>
<div class="line"><a id="l00379" name="l00379"></a><span class="lineno">  379</span><span class="comment"> *   - If you have 1 thread (e.g., via `flow::async::Single_thread_task_loop`) dedicated to processing `*this`,</span></div>
<div class="line"><a id="l00380" name="l00380"></a><span class="lineno">  380</span><span class="comment"> *     then this is particularly straightforward; no need to synchronize on `*this` and/or the `*this`-is-hosed</span></div>
<div class="line"><a id="l00381" name="l00381"></a><span class="lineno">  381</span><span class="comment"> *     flag/mark.</span></div>
<div class="line"><a id="l00382" name="l00382"></a><span class="lineno">  382</span><span class="comment"> *</span></div>
<div class="line"><a id="l00383" name="l00383"></a><span class="lineno">  383</span><span class="comment"> * ### Lifecycle of an out-message ###</span></div>
<div class="line"><a id="l00384" name="l00384"></a><span class="lineno">  384</span><span class="comment"> * #Msg_out represents the message payload.  It is a data structure instance -- nothing more.  Its outer shell sits</span></div>
<div class="line"><a id="l00385" name="l00385"></a><span class="lineno">  385</span><span class="comment"> * wherever it is instantiated; typically either on the stack or in regular heap.  It allocates space for the</span></div>
<div class="line"><a id="l00386" name="l00386"></a><span class="lineno">  386</span><span class="comment"> * the serialization mutated by its `.body_root()` capnp `Builder` based on the `Struct_builder_config` type</span></div>
<div class="line"><a id="l00387" name="l00387"></a><span class="lineno">  387</span><span class="comment"> * chosen at compile-time.  (If you use create_msg(), this light-weight object -- essentially a few scalars -- is</span></div>
<div class="line"><a id="l00388" name="l00388"></a><span class="lineno">  388</span><span class="comment"> * supplied to the `Msg_out` ctor for you.  Otherwise you have to construct one directly and pass-in a</span></div>
<div class="line"><a id="l00389" name="l00389"></a><span class="lineno">  389</span><span class="comment"> * `Builder_config` or `Builder` of the same type.)  This builder *engine* determines where this internal</span></div>
<div class="line"><a id="l00390" name="l00390"></a><span class="lineno">  390</span><span class="comment"> * bulk -- the serialization backing -- lives.  For the rest of this discussion let us assume it is</span></div>
<div class="line"><a id="l00391" name="l00391"></a><span class="lineno">  391</span><span class="comment"> * `shm::classic::Builder::Config` (or jemalloc equivalent); meaning the engine is zero-copy-enabling,</span></div>
<div class="line"><a id="l00392" name="l00392"></a><span class="lineno">  392</span><span class="comment"> * for high perf and other benefits, and therefore allocates backing buffer(s) in SHM.</span></div>
<div class="line"><a id="l00393" name="l00393"></a><span class="lineno">  393</span><span class="comment"> *</span></div>
<div class="line"><a id="l00394" name="l00394"></a><span class="lineno">  394</span><span class="comment"> * #Msg_out, therefore, is similar to a container backed by a SHM-allocating allocator.  It continues to take RAM</span></div>
<div class="line"><a id="l00395" name="l00395"></a><span class="lineno">  395</span><span class="comment"> * resources, and the serialization continues to be accessible, on all ends until *both* of the following occur:</span></div>
<div class="line"><a id="l00396" name="l00396"></a><span class="lineno">  396</span><span class="comment"> *   - The #Msg_out is destroyed.</span></div>
<div class="line"><a id="l00397" name="l00397"></a><span class="lineno">  397</span><span class="comment"> *   - Every #Msg_in_ptr obtained in *any* opposing struc::Channel to have received it (via expect_msg(),</span></div>
<div class="line"><a id="l00398" name="l00398"></a><span class="lineno">  398</span><span class="comment"> *     expect_msgs(), and response-accepting handlers), after it had been send()ed (et al) there, is destroyed --</span></div>
<div class="line"><a id="l00399" name="l00399"></a><span class="lineno">  399</span><span class="comment"> *     along with all derived `Msg_in_ptr`s.  (#Msg_in_ptr is `shared_ptr&lt;Msg_in&gt;`.)</span></div>
<div class="line"><a id="l00400" name="l00400"></a><span class="lineno">  400</span><span class="comment"> *</span></div>
<div class="line"><a id="l00401" name="l00401"></a><span class="lineno">  401</span><span class="comment"> * Suppose you create a #Msg_out and send() it.  At this point there is &quot;virtual&quot; #Msg_in in existence:</span></div>
<div class="line"><a id="l00402" name="l00402"></a><span class="lineno">  402</span><span class="comment"> * the underlying serialization will not be destroyed yet, even if #Msg_out is.  Normally the opposing</span></div>
<div class="line"><a id="l00403" name="l00403"></a><span class="lineno">  403</span><span class="comment"> * struc::Channel will be used to receive the message, in a real #Msg_in, via an aforementioned in-message</span></div>
<div class="line"><a id="l00404" name="l00404"></a><span class="lineno">  404</span><span class="comment"> * handler.  If this does not occur, the message leaks until the containing SHM arena is cleaned-up.</span></div>
<div class="line"><a id="l00405" name="l00405"></a><span class="lineno">  405</span><span class="comment"> * (If you use ipc::session to manage SHM arena(s), which is the normal scenario, then ipc::session will take</span></div>
<div class="line"><a id="l00406" name="l00406"></a><span class="lineno">  406</span><span class="comment"> * care of this for you.  See ipc::session documentation, starting with the namespace doc header.)</span></div>
<div class="line"><a id="l00407" name="l00407"></a><span class="lineno">  407</span><span class="comment"> *</span></div>
<div class="line"><a id="l00408" name="l00408"></a><span class="lineno">  408</span><span class="comment"> * Suppose in your application, at this point, you will never again write to the #Msg_out further (modify it).</span></div>
<div class="line"><a id="l00409" name="l00409"></a><span class="lineno">  409</span><span class="comment"> * You may freely send() the same #Msg_out again.  You may send it through a different struc::Channel or</span></div>
<div class="line"><a id="l00410" name="l00410"></a><span class="lineno">  410</span><span class="comment"> * the same one.  You may do so at will.  You may receive it, obviously, at will as well.  Note, however, that</span></div>
<div class="line"><a id="l00411" name="l00411"></a><span class="lineno">  411</span><span class="comment"> * #Msg_in is not fully symmetrical to #Msg_out: It represents not the container but rather the in-message</span></div>
<div class="line"><a id="l00412" name="l00412"></a><span class="lineno">  412</span><span class="comment"> * *instance*: that particular time you received a message, with a handle to the payload controlled by</span></div>
<div class="line"><a id="l00413" name="l00413"></a><span class="lineno">  413</span><span class="comment"> * the original #Msg_out.  So for one #Msg_out, there may be 2+ `Msg_in`s in existence, across various processes</span></div>
<div class="line"><a id="l00414" name="l00414"></a><span class="lineno">  414</span><span class="comment"> * to have received it.  If one process has received it 2x, then there are potentially 2 `Msg_in`s in existence</span></div>
<div class="line"><a id="l00415" name="l00415"></a><span class="lineno">  415</span><span class="comment"> * in that process.  The original #Msg_out and each #Msg_in each contributes 1 to the cross-process</span></div>
<div class="line"><a id="l00416" name="l00416"></a><span class="lineno">  416</span><span class="comment"> * ref-count.</span></div>
<div class="line"><a id="l00417" name="l00417"></a><span class="lineno">  417</span><span class="comment"> *</span></div>
<div class="line"><a id="l00418" name="l00418"></a><span class="lineno">  418</span><span class="comment"> * Lastly suppose all the same is true, except that you would like to continue modifying the #Msg_out post-`send()`.</span></div>
<div class="line"><a id="l00419" name="l00419"></a><span class="lineno">  419</span><span class="comment"> * This is allowed.  However, this must be done with care.  Of course there is the matter of</span></div>
<div class="line"><a id="l00420" name="l00420"></a><span class="lineno">  420</span><span class="comment"> * synchronization as usual: Behavior is undefined if one reads a message while the #Msg_out is being mutated</span></div>
<div class="line"><a id="l00421" name="l00421"></a><span class="lineno">  421</span><span class="comment"> * in the original process.  While it is conceivable one could use an outside synchronization mechanism for this --</span></div>
<div class="line"><a id="l00422" name="l00422"></a><span class="lineno">  422</span><span class="comment"> * an interprocess mutex for example -- informally we expect the best way is to use your struc::Channel</span></div>
<div class="line"><a id="l00423" name="l00423"></a><span class="lineno">  423</span><span class="comment"> * messaging protocol.  In particular it make sense to avoid any modification of a #Msg_out until one has received</span></div>
<div class="line"><a id="l00424" name="l00424"></a><span class="lineno">  424</span><span class="comment"> * a response to any async_request() of it, with the guarantee that the module receiving that *particular* #Msg_in</span></div>
<div class="line"><a id="l00425" name="l00425"></a><span class="lineno">  425</span><span class="comment"> * in the opposing process shall not further read its contents after issuing the async_request() for that response.</span></div>
<div class="line"><a id="l00426" name="l00426"></a><span class="lineno">  426</span><span class="comment"> *</span></div>
<div class="line"><a id="l00427" name="l00427"></a><span class="lineno">  427</span><span class="comment"> * Lastly suppose `Struct_builder_config` is *not* SHM-based; e.g. Heap_fixed_builder::Config.</span></div>
<div class="line"><a id="l00428" name="l00428"></a><span class="lineno">  428</span><span class="comment"> * In that case, simply, #Msg_out is the original message container backed by an in-local-heap serialization;</span></div>
<div class="line"><a id="l00429" name="l00429"></a><span class="lineno">  429</span><span class="comment"> * and every #Msg_in emitted by a receive-handler is a *copy*, also backed by an in-local-to-receiver-heap</span></div>
<div class="line"><a id="l00430" name="l00430"></a><span class="lineno">  430</span><span class="comment"> * serialization.  While #Msg_out can certainly be send()ed repeatedly, and modified in-between,</span></div>
<div class="line"><a id="l00431" name="l00431"></a><span class="lineno">  431</span><span class="comment"> * this simply has no effect on any resulting `Msg_in`s, as they are copies.</span></div>
<div class="line"><a id="l00432" name="l00432"></a><span class="lineno">  432</span><span class="comment"> *</span></div>
<div class="line"><a id="l00433" name="l00433"></a><span class="lineno">  433</span><span class="comment"> * ### Log-in ###</span></div>
<div class="line"><a id="l00434" name="l00434"></a><span class="lineno">  434</span><span class="comment"> * Internally, each out-message is supplied by `*this` with a *session token*.  In regular operation, every</span></div>
<div class="line"><a id="l00435" name="l00435"></a><span class="lineno">  435</span><span class="comment"> * out-message&#39;s session token is the same value through the lifetime of a `*this`.  Every in-message must also</span></div>
<div class="line"><a id="l00436" name="l00436"></a><span class="lineno">  436</span><span class="comment"> * contain that same session token value.  If an in-message arrives with an unexpected session token value, it</span></div>
<div class="line"><a id="l00437" name="l00437"></a><span class="lineno">  437</span><span class="comment"> * is a pipe-hosing error.  (The rationale for this is beyond the scope of discussion here; it is a safety feature.)</span></div>
<div class="line"><a id="l00438" name="l00438"></a><span class="lineno">  438</span><span class="comment"> * This all happens internally.</span></div>
<div class="line"><a id="l00439" name="l00439"></a><span class="lineno">  439</span><span class="comment"> *</span></div>
<div class="line"><a id="l00440" name="l00440"></a><span class="lineno">  440</span><span class="comment"> * In regular operation, at struc::Channel construction time, the constant session token value must be supplied</span></div>
<div class="line"><a id="l00441" name="l00441"></a><span class="lineno">  441</span><span class="comment"> * as a ctor argument.  This session token must not be nil.  While, formally speaking, any non-nil value will do --</span></div>
<div class="line"><a id="l00442" name="l00442"></a><span class="lineno">  442</span><span class="comment"> * provided the same one is given to the struc::Channel on the other end -- correct use (in terms of safety)</span></div>
<div class="line"><a id="l00443" name="l00443"></a><span class="lineno">  443</span><span class="comment"> * is to provide a properly generated unique token -- on both sides.  Where to get this value, though?  Answer:</span></div>
<div class="line"><a id="l00444" name="l00444"></a><span class="lineno">  444</span><span class="comment"> *</span></div>
<div class="line"><a id="l00445" name="l00445"></a><span class="lineno">  445</span><span class="comment"> * Before constructing any regular-operation `struc::Channel`s, in a given session between two processes A and B,</span></div>
<div class="line"><a id="l00446" name="l00446"></a><span class="lineno">  446</span><span class="comment"> * one shall first construct *one* special-purpose transport::Channel, called the *session master channel*, and wrap it</span></div>
<div class="line"><a id="l00447" name="l00447"></a><span class="lineno">  447</span><span class="comment"> * in a special-purpose struc::Channel on each side.  This is the 2nd ctor form, the one without a `session_token`</span></div>
<div class="line"><a id="l00448" name="l00448"></a><span class="lineno">  448</span><span class="comment"> * arg; one side must pass the value `is_server = true`; the other conversely `is_server = false`.</span></div>
<div class="line"><a id="l00449" name="l00449"></a><span class="lineno">  449</span><span class="comment"> *</span></div>
<div class="line"><a id="l00450" name="l00450"></a><span class="lineno">  450</span><span class="comment"> * This special channel is not yet in logged-in phase; it is in logging-in-as-client phase on 1 side and</span></div>
<div class="line"><a id="l00451" name="l00451"></a><span class="lineno">  451</span><span class="comment"> * logging-in-as-server phase on the other side.  The two `struc::Channel`s must then undergo a rigid, but short,</span></div>
<div class="line"><a id="l00452" name="l00452"></a><span class="lineno">  452</span><span class="comment"> * sequence of steps to get to the logged-in phase (at which point the session master channel enters its own</span></div>
<div class="line"><a id="l00453" name="l00453"></a><span class="lineno">  453</span><span class="comment"> * regular-operation phase; the purpose of that channel from that point on is unspecified here -- but read on).</span></div>
<div class="line"><a id="l00454" name="l00454"></a><span class="lineno">  454</span><span class="comment"> *</span></div>
<div class="line"><a id="l00455" name="l00455"></a><span class="lineno">  455</span><span class="comment"> * Namely: the client peer must create a message as normal (create_msg() or #Msg_out construction),</span></div>
<div class="line"><a id="l00456" name="l00456"></a><span class="lineno">  456</span><span class="comment"> * fill out the returned out-message as desired, and async_request() it.</span></div>
<div class="line"><a id="l00457" name="l00457"></a><span class="lineno">  457</span><span class="comment"> * The server peer conversely must invoke expect_log_in_request(), exactly once, handle the incoming request</span></div>
<div class="line"><a id="l00458" name="l00458"></a><span class="lineno">  458</span><span class="comment"> * by filling out a response out-message, and send() that (response-supplying form is mandatory).</span></div>
<div class="line"><a id="l00459" name="l00459"></a><span class="lineno">  459</span><span class="comment"> *   - The server peer `*this` enters logged-in (regular-operation) phase upon `send()`ing the log-in response.</span></div>
<div class="line"><a id="l00460" name="l00460"></a><span class="lineno">  460</span><span class="comment"> *     Did you invoke send() successfully?  Congrats: you&#39;re in regular-operation.</span></div>
<div class="line"><a id="l00461" name="l00461"></a><span class="lineno">  461</span><span class="comment"> *   - The client peer `*this` enters logged-in (regular-operation) phase upon receiving that log-in response</span></div>
<div class="line"><a id="l00462" name="l00462"></a><span class="lineno">  462</span><span class="comment"> *     Did your handler for the response get fired?  Congrats: you&#39;re in regular-operation.</span></div>
<div class="line"><a id="l00463" name="l00463"></a><span class="lineno">  463</span><span class="comment"> *</span></div>
<div class="line"><a id="l00464" name="l00464"></a><span class="lineno">  464</span><span class="comment"> * While this mechanism is fairly general, and hopefully reasonably easy to operate, in practice most users will</span></div>
<div class="line"><a id="l00465" name="l00465"></a><span class="lineno">  465</span><span class="comment"> * not need to ever do so themselves.  Instead: On the server side, establish a `Server_session` (see</span></div>
<div class="line"><a id="l00466" name="l00466"></a><span class="lineno">  466</span><span class="comment"> * session::Session_server).  On the client side, establish a `Client_session`.  They will operate an adequate</span></div>
<div class="line"><a id="l00467" name="l00467"></a><span class="lineno">  467</span><span class="comment"> * session master channel internally.  `Server_session` and `Client_session` shall then each reach their PEER state,</span></div>
<div class="line"><a id="l00468" name="l00468"></a><span class="lineno">  468</span><span class="comment"> * at which point they each satisfy the formal session::Session concept (see session::Session doc header).  Now,</span></div>
<div class="line"><a id="l00469" name="l00469"></a><span class="lineno">  469</span><span class="comment"> * session::Session::session_token() shall return the uniquely generated session token.  This value shall be passed to</span></div>
<div class="line"><a id="l00470" name="l00470"></a><span class="lineno">  470</span><span class="comment"> * all subsequent `struc::Channel`s in the session, into their ctors (possibly via internal delegation).</span></div>
<div class="line"><a id="l00471" name="l00471"></a><span class="lineno">  471</span><span class="comment"> * These subsequent `struc::Channel`s do not need a log-in phase and are immediately in regular-operation.</span></div>
<div class="line"><a id="l00472" name="l00472"></a><span class="lineno">  472</span><span class="comment"> *</span></div>
<div class="line"><a id="l00473" name="l00473"></a><span class="lineno">  473</span><span class="comment"> * Therefore, the only time a user must worry about session tokens at all is when creating a regular-operation</span></div>
<div class="line"><a id="l00474" name="l00474"></a><span class="lineno">  474</span><span class="comment"> * struc::Channel, and even then only if no tag-form struc::Channel ctor is applicable.  In that case:</span></div>
<div class="line"><a id="l00475" name="l00475"></a><span class="lineno">  475</span><span class="comment"> *   - Access session::Session::session_token().</span></div>
<div class="line"><a id="l00476" name="l00476"></a><span class="lineno">  476</span><span class="comment"> *   - Pass the result into struc::Channel ctor on each side.</span></div>
<div class="line"><a id="l00477" name="l00477"></a><span class="lineno">  477</span><span class="comment"> *</span></div>
<div class="line"><a id="l00478" name="l00478"></a><span class="lineno">  478</span><span class="comment"> * Incidentally, `Session` (as implemented by `Server_session`, `Client_session`, and variants) can also easily open new</span></div>
<div class="line"><a id="l00479" name="l00479"></a><span class="lineno">  479</span><span class="comment"> * `Channel`s.  Internally they do so by leveraging various features of struc::Channel as applied to the *one*</span></div>
<div class="line"><a id="l00480" name="l00480"></a><span class="lineno">  480</span><span class="comment"> * (per process A-B session) session master channel.  Each `Channel` obtained this way can then be fed (upgraded) into</span></div>
<div class="line"><a id="l00481" name="l00481"></a><span class="lineno">  481</span><span class="comment"> * a new struc::Channel, if indeed structured messaging is desired for that transport::Channel.  The information in</span></div>
<div class="line"><a id="l00482" name="l00482"></a><span class="lineno">  482</span><span class="comment"> * this paragraph is, formally speaking, outside the purview of struc::Channel API, but I mention it here</span></div>
<div class="line"><a id="l00483" name="l00483"></a><span class="lineno">  483</span><span class="comment"> * for context.  For more detail see session::Session (and its impls session::Server_session, session::Client_session</span></div>
<div class="line"><a id="l00484" name="l00484"></a><span class="lineno">  484</span><span class="comment"> * and variants).</span></div>
<div class="line"><a id="l00485" name="l00485"></a><span class="lineno">  485</span><span class="comment"> *</span></div>
<div class="line"><a id="l00486" name="l00486"></a><span class="lineno">  486</span><span class="comment"> * @todo struc::Channel should probably be made move-constructible and move-assignable.  No concept requires</span></div>
<div class="line"><a id="l00487" name="l00487"></a><span class="lineno">  487</span><span class="comment"> * this, unlike with many other classes and class templates in ::ipc, so it is less essential; but both for</span></div>
<div class="line"><a id="l00488" name="l00488"></a><span class="lineno">  488</span><span class="comment"> * consistency and usability it would be good.  It would also make some APIs possible that currently would require</span></div>
<div class="line"><a id="l00489" name="l00489"></a><span class="lineno">  489</span><span class="comment"> * the user to explicitly wrap this class in a `unique_ptr`.  For example, imagine</span></div>
<div class="line"><a id="l00490" name="l00490"></a><span class="lineno">  490</span><span class="comment"> * a `Session::Structured_channel Session::structured_channel_upgrade(Channel_obj&amp;&amp; channel, ...)` that</span></div>
<div class="line"><a id="l00491" name="l00491"></a><span class="lineno">  491</span><span class="comment"> * constructs a suitably-typed struc::Channel, subsuming the raw `channel` just opened in that session::Session, and</span></div>
<div class="line"><a id="l00492" name="l00492"></a><span class="lineno">  492</span><span class="comment"> * returns that guy.  Currently it would need to return `unique_ptr&lt;Session::Structured_channel&gt;` or something.</span></div>
<div class="line"><a id="l00493" name="l00493"></a><span class="lineno">  493</span><span class="comment"> *</span></div>
<div class="line"><a id="l00494" name="l00494"></a><span class="lineno">  494</span><span class="comment"> * @internal</span></div>
<div class="line"><a id="l00495" name="l00495"></a><span class="lineno">  495</span><span class="comment"> * ### Implementation overview (threads U, W) ###</span></div>
<div class="line"><a id="l00496" name="l00496"></a><span class="lineno">  496</span><span class="comment"> * struc::Channel sits atop several layers of concepts and objects implementing them: from the raw</span></div>
<div class="line"><a id="l00497" name="l00497"></a><span class="lineno">  497</span><span class="comment"> * transports (transport::asio_local_stream_socket namespace, Persistent_mq_handle concept and impls); to</span></div>
<div class="line"><a id="l00498" name="l00498"></a><span class="lineno">  498</span><span class="comment"> * the component Blob_sender, Blob_receiver, Native_handle_sender, Native_handle_receiver impls; to the</span></div>
<div class="line"><a id="l00499" name="l00499"></a><span class="lineno">  499</span><span class="comment"> * transport::Channel (#Owned_channel) bundling them together; and lastly -- and most immediately relevantly --</span></div>
<div class="line"><a id="l00500" name="l00500"></a><span class="lineno">  500</span><span class="comment"> * to the struc::sync_io::Channel core.  (The latter is aliased as struc::Channel::Sync_io_obj.)</span></div>
<div class="line"><a id="l00501" name="l00501"></a><span class="lineno">  501</span><span class="comment"> *</span></div>
<div class="line"><a id="l00502" name="l00502"></a><span class="lineno">  502</span><span class="comment"> * In implementing struc::Channel, then, we already rely on much logic that is abstracted-away; we only</span></div>
<div class="line"><a id="l00503" name="l00503"></a><span class="lineno">  503</span><span class="comment"> * need to &quot;decorate&quot; their work by, essentially, some pre- and post-processing -- to provide, specifically,</span></div>
<div class="line"><a id="l00504" name="l00504"></a><span class="lineno">  504</span><span class="comment"> * the features explicitly outlined above publicly (&quot;What does struc::Channel add, broadly speaking, that</span></div>
<div class="line"><a id="l00505" name="l00505"></a><span class="lineno">  505</span><span class="comment"> * transport::Channel does not already have?&quot;).</span></div>
<div class="line"><a id="l00506" name="l00506"></a><span class="lineno">  506</span><span class="comment"> *</span></div>
<div class="line"><a id="l00507" name="l00507"></a><span class="lineno">  507</span><span class="comment"> * Perf, in particular low latency, is essential for this work-horse class template.  For performance -- or perhaps</span></div>
<div class="line"><a id="l00508" name="l00508"></a><span class="lineno">  508</span><span class="comment"> * more accurately for most direct/deterministic flow control/thread structure --</span></div>
<div class="line"><a id="l00509" name="l00509"></a><span class="lineno">  509</span><span class="comment"> * we use `sync_io` objects throughout; our #Sync_io_obj core (`m_sync_io`) and the #Owned_channel subsumed by it</span></div>
<div class="line"><a id="l00510" name="l00510"></a><span class="lineno">  510</span><span class="comment"> * create no handler-invoking threads.  We, however, are ourselves an async-I/O-pattern object, and therefore</span></div>
<div class="line"><a id="l00511" name="l00511"></a><span class="lineno">  511</span><span class="comment"> * essentially by definition of how that pattern works we start a worker thread W in which to (1) perform all</span></div>
<div class="line"><a id="l00512" name="l00512"></a><span class="lineno">  512</span><span class="comment"> * asynchronously-delayed (i.e., contingent on event async-waits) work of all the aforementioned layers below</span></div>
<div class="line"><a id="l00513" name="l00513"></a><span class="lineno">  513</span><span class="comment"> * us (helpfully encapsulated in #Sync_io_obj `m_sync_io`); and (2) invoke user-supplied completion handlers.</span></div>
<div class="line"><a id="l00514" name="l00514"></a><span class="lineno">  514</span><span class="comment"> *</span></div>
<div class="line"><a id="l00515" name="l00515"></a><span class="lineno">  515</span><span class="comment"> * This thread W (`m_worker`) is the only async-worker thread.  Everything else is (to reiterate) `sync_io`-pattern.</span></div>
<div class="line"><a id="l00516" name="l00516"></a><span class="lineno">  516</span><span class="comment"> *</span></div>
<div class="line"><a id="l00517" name="l00517"></a><span class="lineno">  517</span><span class="comment"> * Thread U is (as per usual) the term for the user&#39;s calling thread (as usual they may of course use 2+ threads if</span></div>
<div class="line"><a id="l00518" name="l00518"></a><span class="lineno">  518</span><span class="comment"> * desired; but via #m_mutex and #m_sync_op_mutex we essentially make all</span></div>
<div class="line"><a id="l00519" name="l00519"></a><span class="lineno">  519</span><span class="comment"> * such calls non-concurrent... so as usual we call it thread U,</span></div>
<div class="line"><a id="l00520" name="l00520"></a><span class="lineno">  520</span><span class="comment"> * as if it is one thread).  We do allow transmission APIs to be invoked from within completion handlers of our</span></div>
<div class="line"><a id="l00521" name="l00521"></a><span class="lineno">  521</span><span class="comment"> * own other transmission APIs (e.g., `send()` or `expect_msg()` directly within `expect_msg()` handler).</span></div>
<div class="line"><a id="l00522" name="l00522"></a><span class="lineno">  522</span><span class="comment"> * (sync_request(), being blocking, is the exception.)</span></div>
<div class="line"><a id="l00523" name="l00523"></a><span class="lineno">  523</span><span class="comment"> *</span></div>
<div class="line"><a id="l00524" name="l00524"></a><span class="lineno">  524</span><span class="comment"> * Since there are 2+ threads, U and W, with async-processing in the latter potentially occurring concurrently with</span></div>
<div class="line"><a id="l00525" name="l00525"></a><span class="lineno">  525</span><span class="comment"> * API calls in the former -- and with our explicitly allowing concurrent calls on the same `*this` --</span></div>
<div class="line"><a id="l00526" name="l00526"></a><span class="lineno">  526</span><span class="comment"> * there&#39;s a big fat mutex `m_mutex` locked around most code.  That said thread contention</span></div>
<div class="line"><a id="l00527" name="l00527"></a><span class="lineno">  527</span><span class="comment"> * is unlikely in most use cases, unless the user causes it in their own code.  (Details omitted here.)</span></div>
<div class="line"><a id="l00528" name="l00528"></a><span class="lineno">  528</span><span class="comment"> *</span></div>
<div class="line"><a id="l00529" name="l00529"></a><span class="lineno">  529</span><span class="comment"> * ### Implementation ###</span></div>
<div class="line"><a id="l00530" name="l00530"></a><span class="lineno">  530</span><span class="comment"> * Unlike in the past, when `*this` template was monolithic, now it is split into the core functionality</span></div>
<div class="line"><a id="l00531" name="l00531"></a><span class="lineno">  531</span><span class="comment"> * in sync_io::Channel (#Sync_io_obj `m_sync_io`) and the (relatively limited) logic necessary on top</span></div>
<div class="line"><a id="l00532" name="l00532"></a><span class="lineno">  532</span><span class="comment"> * of this to adapt that into the async-I/O pattern, wherein user handlers fire from thread W, and</span></div>
<div class="line"><a id="l00533" name="l00533"></a><span class="lineno">  533</span><span class="comment"> * any necessary internal async ops occur automatically in thread W without user participation.</span></div>
<div class="line"><a id="l00534" name="l00534"></a><span class="lineno">  534</span><span class="comment"> *</span></div>
<div class="line"><a id="l00535" name="l00535"></a><span class="lineno">  535</span><span class="comment"> * Therefore the really complicated stuff is abstracted away in the #Sync_io_obj.  The adapting logic is</span></div>
<div class="line"><a id="l00536" name="l00536"></a><span class="lineno">  536</span><span class="comment"> * simple enough to be understandable by reading the code and inline comments, especially on the data members.</span></div>
<div class="line"><a id="l00537" name="l00537"></a><span class="lineno">  537</span><span class="comment"> * @endinternal</span></div>
<div class="line"><a id="l00538" name="l00538"></a><span class="lineno">  538</span><span class="comment"> *</span></div>
<div class="line"><a id="l00539" name="l00539"></a><span class="lineno">  539</span><span class="comment"> * @tparam Channel_obj</span></div>
<div class="line"><a id="l00540" name="l00540"></a><span class="lineno">  540</span><span class="comment"> *         An instance of transport::Channel class template.  See transport::Channel doc header.  It must have</span></div>
<div class="line"><a id="l00541" name="l00541"></a><span class="lineno">  541</span><span class="comment"> *         `Channel_obj::S_IS_SYNC_IO_OBJ == true`.  Reminder: the template params to</span></div>
<div class="line"><a id="l00542" name="l00542"></a><span class="lineno">  542</span><span class="comment"> *         transport::Channel template (along with certain documented requirements on how to use its API when</span></div>
<div class="line"><a id="l00543" name="l00543"></a><span class="lineno">  543</span><span class="comment"> *         initializing it before feeding it to struc::Channel ctor) determine the number and nature of underlying</span></div>
<div class="line"><a id="l00544" name="l00544"></a><span class="lineno">  544</span><span class="comment"> *         transport pipes of the channel.  struc::Channel will work with anything you specify, as long as it</span></div>
<div class="line"><a id="l00545" name="l00545"></a><span class="lineno">  545</span><span class="comment"> *         results in a `sync_io`-core-bearing transport::Channel object in PEER state fed to `*this` ctor.</span></div>
<div class="line"><a id="l00546" name="l00546"></a><span class="lineno">  546</span><span class="comment"> * @tparam Message_body</span></div>
<div class="line"><a id="l00547" name="l00547"></a><span class="lineno">  547</span><span class="comment"> *         The capnp-generated class for the capnp-`struct` describing the schema of messages you intend to transmit</span></div>
<div class="line"><a id="l00548" name="l00548"></a><span class="lineno">  548</span><span class="comment"> *         over this channel.  (Therefore, in particular, `Message_body::Builder` and `Message_body::Reader` shall</span></div>
<div class="line"><a id="l00549" name="l00549"></a><span class="lineno">  549</span><span class="comment"> *         be capnp-generated classes as well.)  The contents of this capnp-`struct` are arbitrary -- whatever suits</span></div>
<div class="line"><a id="l00550" name="l00550"></a><span class="lineno">  550</span><span class="comment"> *         one&#39;s purpose -- except for the following requirement: It must contain a top-level anon capnp-`union`.</span></div>
<div class="line"><a id="l00551" name="l00551"></a><span class="lineno">  551</span><span class="comment"> *         #Msg_which shall therefore be the enumeration of the possible active value of this capnp-`union`.</span></div>
<div class="line"><a id="l00552" name="l00552"></a><span class="lineno">  552</span><span class="comment"> *         This union conceptually corresponds to the different types of messages one might transmit over the channel.</span></div>
<div class="line"><a id="l00553" name="l00553"></a><span class="lineno">  553</span><span class="comment"> * @tparam Struct_builder_config</span></div>
<div class="line"><a id="l00554" name="l00554"></a><span class="lineno">  554</span><span class="comment"> *         A type satisfying the concept Struct_builder::Config, with the additional requirement that</span></div>
<div class="line"><a id="l00555" name="l00555"></a><span class="lineno">  555</span><span class="comment"> *         each `flow::util::Blob B` emitted by `Struct_builder_config::Builder::emit_serialization()` satisfies</span></div>
<div class="line"><a id="l00556" name="l00556"></a><span class="lineno">  556</span><span class="comment"> *         the following condition:</span></div>
<div class="line"><a id="l00557" name="l00557"></a><span class="lineno">  557</span><span class="comment"> *         `B.size() &lt;= M`, where `M` is the lower of `Owned_channel::send_blob_max_size()`,</span></div>
<div class="line"><a id="l00558" name="l00558"></a><span class="lineno">  558</span><span class="comment"> *         `Owned_channel::send_meta_blob_max_size()`, for the applicable 1-2 pipes in #Owned_channel.</span></div>
<div class="line"><a id="l00559" name="l00559"></a><span class="lineno">  559</span><span class="comment"> *         An object of this type is passed to ctor.</span></div>
<div class="line"><a id="l00560" name="l00560"></a><span class="lineno">  560</span><span class="comment"> *         This determines how, internally, `*this` shall transform structured out-messages provided by the user</span></div>
<div class="line"><a id="l00561" name="l00561"></a><span class="lineno">  561</span><span class="comment"> *         into binary blobs sent via the #Owned_channel.</span></div>
<div class="line"><a id="l00562" name="l00562"></a><span class="lineno">  562</span><span class="comment"> *         This Struct_builder_config must match the opposing peer&#39;s choice of Struct_reader_config.</span></div>
<div class="line"><a id="l00563" name="l00563"></a><span class="lineno">  563</span><span class="comment"> *         E.g., if this is Heap_fixed_builder::Config, then the other guy&#39;s</span></div>
<div class="line"><a id="l00564" name="l00564"></a><span class="lineno">  564</span><span class="comment"> *         thingie is Heap_reader::Config.</span></div>
<div class="line"><a id="l00565" name="l00565"></a><span class="lineno">  565</span><span class="comment"> *         In practice it is usually best to use a struc::Channel alias (as of this writing</span></div>
<div class="line"><a id="l00566" name="l00566"></a><span class="lineno">  566</span><span class="comment"> *         Channel_via_heap, shm::classic::Channel, shm::arena_lend::jemalloc::Channel)</span></div>
<div class="line"><a id="l00567" name="l00567"></a><span class="lineno">  567</span><span class="comment"> *         and accordingly to use one of the Channel_base tags:</span></div>
<div class="line"><a id="l00568" name="l00568"></a><span class="lineno">  568</span><span class="comment"> *         Channel_base::S_SERIALIZE_VIA_HEAP, Channel_base::S_SERIALIZE_VIA_APP_SHM,</span></div>
<div class="line"><a id="l00569" name="l00569"></a><span class="lineno">  569</span><span class="comment"> *         Channel_base::S_SERIALIZE_VIA_SESSION_SHM.</span></div>
<div class="line"><a id="l00570" name="l00570"></a><span class="lineno">  570</span><span class="comment"> *         See the documentation on the latter 3 for useful suggestions.</span></div>
<div class="line"><a id="l00571" name="l00571"></a><span class="lineno">  571</span><span class="comment"> * @tparam Struct_reader_config</span></div>
<div class="line"><a id="l00572" name="l00572"></a><span class="lineno">  572</span><span class="comment"> *         A type satisfying the concept Struct_reader::Config.  An object of this type is passed to ctor.</span></div>
<div class="line"><a id="l00573" name="l00573"></a><span class="lineno">  573</span><span class="comment"> *         This determines how, internally, `*this` shall transform unstructured in-blobs received from the other</span></div>
<div class="line"><a id="l00574" name="l00574"></a><span class="lineno">  574</span><span class="comment"> *         peer over the #Owned_channel into structured in-messages emitted to the user.</span></div>
<div class="line"><a id="l00575" name="l00575"></a><span class="lineno">  575</span><span class="comment"> *         This Struct_reader_config must match the opposing peer&#39;s choice of Struct_builder_config.</span></div>
<div class="line"><a id="l00576" name="l00576"></a><span class="lineno">  576</span><span class="comment"> *         See `Struct_builder_config` notes just above.</span></div>
<div class="line"><a id="l00577" name="l00577"></a><span class="lineno">  577</span><span class="comment"> */</span></div>
<div class="line"><a id="l00578" name="l00578"></a><span class="lineno">  578</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Channel_obj, <span class="keyword">typename</span> Message_body,</div>
<div class="line"><a id="l00579" name="l00579"></a><span class="lineno">  579</span>         <span class="keyword">typename</span> Struct_builder_config, <span class="keyword">typename</span> Struct_reader_config&gt;</div>
<div class="line"><a id="l00580" name="l00580"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html">  580</a></span><span class="keyword">class </span><a class="code hl_class" href="classipc_1_1transport_1_1struc_1_1Channel.html">Channel</a> :</div>
<div class="line"><a id="l00581" name="l00581"></a><span class="lineno">  581</span>  <span class="keyword">private</span> boost::noncopyable,</div>
<div class="line"><a id="l00582" name="l00582"></a><span class="lineno">  582</span>  <span class="keyword">public</span> flow::log::Log_context</div>
<div class="line"><a id="l00583" name="l00583"></a><span class="lineno">  583</span>{</div>
<div class="line"><a id="l00584" name="l00584"></a><span class="lineno">  584</span><span class="keyword">public</span>:</div>
<div class="line"><a id="l00585" name="l00585"></a><span class="lineno">  585</span>  <span class="comment">// Types.</span></div>
<div class="line"><a id="l00586" name="l00586"></a><span class="lineno">  586</span><span class="comment"></span> </div>
<div class="line"><a id="l00587" name="l00587"></a><span class="lineno">  587</span><span class="comment">  /// Useful for generic programming, the `sync_io`-pattern counterpart to `*this` type.</span></div>
<div class="line"><a id="l00588" name="l00588"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a9426e8e562dd4c9ea1bc1f69f47bb99f">  588</a></span><span class="comment"></span>  <span class="keyword">using </span><a class="code hl_class" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html">Sync_io_obj</a> = <a class="code hl_class" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html">sync_io::Channel</a>&lt;Channel_obj, Message_body,</div>
<div class="line"><a id="l00589" name="l00589"></a><span class="lineno">  589</span>                                       Struct_builder_config, Struct_reader_config&gt;;<span class="comment"></span></div>
<div class="line"><a id="l00590" name="l00590"></a><span class="lineno">  590</span><span class="comment">  /// You may disregard.</span></div>
<div class="line"><a id="l00591" name="l00591"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae01d976c856e82b4370e9e69e6128cff">  591</a></span><span class="comment"></span>  <span class="keyword">using </span><a class="code hl_class" href="classipc_1_1transport_1_1Null__peer.html">Async_io_obj</a> = <a class="code hl_class" href="classipc_1_1transport_1_1Null__peer.html">Null_peer</a>;</div>
<div class="line"><a id="l00592" name="l00592"></a><span class="lineno">  592</span><span class="comment"></span> </div>
<div class="line"><a id="l00593" name="l00593"></a><span class="lineno">  593</span><span class="comment">  /// Short-hand for the transport::Channel type passed into ctor and returned by owned_channel().</span></div>
<div class="line"><a id="l00594" name="l00594"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4a0188052c15cab70d712f41b0e74ba7">  594</a></span><span class="comment"></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4a0188052c15cab70d712f41b0e74ba7">Owned_channel</a> = <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a4abac89dbd4d26c79b7915990f751a76">Sync_io_obj::Owned_channel</a>;</div>
<div class="line"><a id="l00595" name="l00595"></a><span class="lineno">  595</span><span class="comment"></span> </div>
<div class="line"><a id="l00596" name="l00596"></a><span class="lineno">  596</span><span class="comment">  /// Short-hand for the builder engine type.</span></div>
<div class="line"><a id="l00597" name="l00597"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a346752b515926a2938ed2adb9de92b1e">  597</a></span><span class="comment"></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a346752b515926a2938ed2adb9de92b1e">Builder_config</a> = <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a8a59bbc3c6a7191b316b23661d8ba6e3">Sync_io_obj::Builder_config</a>;<span class="comment"></span></div>
<div class="line"><a id="l00598" name="l00598"></a><span class="lineno">  598</span><span class="comment">  /// Short-hand for the reader engine type.</span></div>
<div class="line"><a id="l00599" name="l00599"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ad3ff78f00b7f230562d713ec6cf8499c">  599</a></span><span class="comment"></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ad3ff78f00b7f230562d713ec6cf8499c">Reader_config</a> = <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a14a7166b2f8c117ce6ddafe943d036fa">Sync_io_obj::Reader_config</a>;</div>
<div class="line"><a id="l00600" name="l00600"></a><span class="lineno">  600</span><span class="comment"></span> </div>
<div class="line"><a id="l00601" name="l00601"></a><span class="lineno">  601</span><span class="comment">  /// Short-hand for the `Message_body` template param, this is the capnp message schema transmissible over `*this`.</span></div>
<div class="line"><a id="l00602" name="l00602"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a27a273ed7e1aca34b721fea22c869a41">  602</a></span><span class="comment"></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a27a273ed7e1aca34b721fea22c869a41">Msg_body</a> = <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a34e183c252390f369f121074772c14c4">Sync_io_obj::Msg_body</a>;</div>
<div class="line"><a id="l00603" name="l00603"></a><span class="lineno">  603</span><span class="comment"></span> </div>
<div class="line"><a id="l00604" name="l00604"></a><span class="lineno">  604</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00605" name="l00605"></a><span class="lineno">  605</span><span class="comment">   * Short-hand for the `Message_body` top-level anon capnp-`union` enumeration.</span></div>
<div class="line"><a id="l00606" name="l00606"></a><span class="lineno">  606</span><span class="comment">   * This important type determines the type of in-message or out-message the (remote or local, respectively) user</span></div>
<div class="line"><a id="l00607" name="l00607"></a><span class="lineno">  607</span><span class="comment">   * chose.</span></div>
<div class="line"><a id="l00608" name="l00608"></a><span class="lineno">  608</span><span class="comment">   */</span></div>
<div class="line"><a id="l00609" name="l00609"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a9a0382aa663c177f2a38b576d06b251e">  609</a></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a9a0382aa663c177f2a38b576d06b251e">Msg_which</a> = <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a1572a1b1cb4a72ea57f7841a5e78759b">Sync_io_obj::Msg_which</a>;</div>
<div class="line"><a id="l00610" name="l00610"></a><span class="lineno">  610</span><span class="comment"></span> </div>
<div class="line"><a id="l00611" name="l00611"></a><span class="lineno">  611</span><span class="comment">  /// Stylistic nicety, indicating that a #Msg_which applies to an in-message rather than an out-message.</span></div>
<div class="line"><a id="l00612" name="l00612"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">  612</a></span><span class="comment"></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">Msg_which_in</a> = <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#aa40c3ec3f45cdfea9360f7f35b9ade3c">Sync_io_obj::Msg_which_in</a>;</div>
<div class="line"><a id="l00613" name="l00613"></a><span class="lineno">  613</span><span class="comment"></span> </div>
<div class="line"><a id="l00614" name="l00614"></a><span class="lineno">  614</span><span class="comment">  /// Stylistic nicety, indicating that a #Msg_which applies to an out-message rather than an in-message.</span></div>
<div class="line"><a id="l00615" name="l00615"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4cc597a9ff8f460f5a773005f0a05805">  615</a></span><span class="comment"></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4cc597a9ff8f460f5a773005f0a05805">Msg_which_out</a> = <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a7a731cdae5217ed9e867fb80c1fb0fd9">Sync_io_obj::Msg_which_out</a>;</div>
<div class="line"><a id="l00616" name="l00616"></a><span class="lineno">  616</span><span class="comment"></span> </div>
<div class="line"><a id="l00617" name="l00617"></a><span class="lineno">  617</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00618" name="l00618"></a><span class="lineno">  618</span><span class="comment">   * Encapsulation of any out-message *payload* sent or meant to be sent via send() (et al) by a `*this`</span></div>
<div class="line"><a id="l00619" name="l00619"></a><span class="lineno">  619</span><span class="comment">   * of this type.  A #Msg_out is container-like, in that there is only one of these regardless of how</span></div>
<div class="line"><a id="l00620" name="l00620"></a><span class="lineno">  620</span><span class="comment">   * many times one has sent it -- even in other `*this`es of the same struc::Channel concrete type.</span></div>
<div class="line"><a id="l00621" name="l00621"></a><span class="lineno">  621</span><span class="comment">   *</span></div>
<div class="line"><a id="l00622" name="l00622"></a><span class="lineno">  622</span><span class="comment">   * @see &quot;Lifecycle of an out-message&quot; section of this class&#39;s doc header.</span></div>
<div class="line"><a id="l00623" name="l00623"></a><span class="lineno">  623</span><span class="comment">   */</span></div>
<div class="line"><a id="l00624" name="l00624"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">  624</a></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">Msg_out</a> = <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a83fb4462a8d4045bdb56b694bf80393c">Sync_io_obj::Msg_out</a>;</div>
<div class="line"><a id="l00625" name="l00625"></a><span class="lineno">  625</span><span class="comment"></span> </div>
<div class="line"><a id="l00626" name="l00626"></a><span class="lineno">  626</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00627" name="l00627"></a><span class="lineno">  627</span><span class="comment">   * Encapsulation of any in-message *instance* received by a `*this` of this type.</span></div>
<div class="line"><a id="l00628" name="l00628"></a><span class="lineno">  628</span><span class="comment">   *</span></div>
<div class="line"><a id="l00629" name="l00629"></a><span class="lineno">  629</span><span class="comment">   * @see &quot;Lifecycle of an out-message&quot; section of this class&#39;s doc header.</span></div>
<div class="line"><a id="l00630" name="l00630"></a><span class="lineno">  630</span><span class="comment">   *</span></div>
<div class="line"><a id="l00631" name="l00631"></a><span class="lineno">  631</span><span class="comment">   * @see #Msg_in_ptr</span></div>
<div class="line"><a id="l00632" name="l00632"></a><span class="lineno">  632</span><span class="comment">   */</span></div>
<div class="line"><a id="l00633" name="l00633"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a05d1cd2fc6a81a39c50a24322fb5c165">  633</a></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a05d1cd2fc6a81a39c50a24322fb5c165">Msg_in</a> = <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#ac3da0ac1306b63c9e38c47b8c31e3cd2">Sync_io_obj::Msg_in</a>;</div>
<div class="line"><a id="l00634" name="l00634"></a><span class="lineno">  634</span><span class="comment"></span> </div>
<div class="line"><a id="l00635" name="l00635"></a><span class="lineno">  635</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00636" name="l00636"></a><span class="lineno">  636</span><span class="comment">   * A ref-counted handle to #Msg_in.  Generally one obtains a #Msg_in via a handle thereto via</span></div>
<div class="line"><a id="l00637" name="l00637"></a><span class="lineno">  637</span><span class="comment">   * handler passed to event registration APIs such as expect_msgs() or async_request(); then one</span></div>
<div class="line"><a id="l00638" name="l00638"></a><span class="lineno">  638</span><span class="comment">   * accesses its contents via capnp-generated accessors on Msg_in::body_root().</span></div>
<div class="line"><a id="l00639" name="l00639"></a><span class="lineno">  639</span><span class="comment">   */</span></div>
<div class="line"><a id="l00640" name="l00640"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">  640</a></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a> = <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#acde2b3866547a30958035203d9d89928">Sync_io_obj::Msg_in_ptr</a>;</div>
<div class="line"><a id="l00641" name="l00641"></a><span class="lineno">  641</span><span class="comment"></span> </div>
<div class="line"><a id="l00642" name="l00642"></a><span class="lineno">  642</span><span class="comment">  /// Short-hand for convenience for the same thing in non-parameterized base Channel_base.</span></div>
<div class="line"><a id="l00643" name="l00643"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4d4995b27b7a6944fbcceee7657f6413">  643</a></span><span class="comment"></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4d4995b27b7a6944fbcceee7657f6413">msg_id_out_t</a> = <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a9b5d17887c9ad1e37081bf4ae4a70e65">Sync_io_obj::msg_id_out_t</a>;</div>
<div class="line"><a id="l00644" name="l00644"></a><span class="lineno">  644</span> </div>
<div class="line"><a id="l00645" name="l00645"></a><span class="lineno">  645</span>  <span class="comment">// Constructors/destructor.</span></div>
<div class="line"><a id="l00646" name="l00646"></a><span class="lineno">  646</span><span class="comment"></span> </div>
<div class="line"><a id="l00647" name="l00647"></a><span class="lineno">  647</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00648" name="l00648"></a><span class="lineno">  648</span><span class="comment">   * All explicit constructors: signatures match exactly those of struc::sync_io::Channel (a/k/a #Sync_io_obj).</span></div>
<div class="line"><a id="l00649" name="l00649"></a><span class="lineno">  649</span><span class="comment">   *</span></div>
<div class="line"><a id="l00650" name="l00650"></a><span class="lineno">  650</span><span class="comment">   * @see struc::sync_io::Channel ctor doc headers.  They&#39;re important!</span></div>
<div class="line"><a id="l00651" name="l00651"></a><span class="lineno">  651</span><span class="comment">   *</span></div>
<div class="line"><a id="l00652" name="l00652"></a><span class="lineno">  652</span><span class="comment">   * @tparam Ctor_args</span></div>
<div class="line"><a id="l00653" name="l00653"></a><span class="lineno">  653</span><span class="comment">   *         Arguments per above.</span></div>
<div class="line"><a id="l00654" name="l00654"></a><span class="lineno">  654</span><span class="comment">   * @param logger_ptr</span></div>
<div class="line"><a id="l00655" name="l00655"></a><span class="lineno">  655</span><span class="comment">   *        See above.</span></div>
<div class="line"><a id="l00656" name="l00656"></a><span class="lineno">  656</span><span class="comment">   * @param channel</span></div>
<div class="line"><a id="l00657" name="l00657"></a><span class="lineno">  657</span><span class="comment">   *        See above.</span></div>
<div class="line"><a id="l00658" name="l00658"></a><span class="lineno">  658</span><span class="comment">   * @param ctor_args</span></div>
<div class="line"><a id="l00659" name="l00659"></a><span class="lineno">  659</span><span class="comment">   *        See above.</span></div>
<div class="line"><a id="l00660" name="l00660"></a><span class="lineno">  660</span><span class="comment">   */</span></div>
<div class="line"><a id="l00661" name="l00661"></a><span class="lineno">  661</span>  <span class="keyword">template</span>&lt;<span class="keyword">typename</span>... Ctor_args&gt;</div>
<div class="line"><a id="l00662" name="l00662"></a><span class="lineno">  662</span>  <span class="keyword">explicit</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#abe73bfa20ca0207ac8aa63d26d54de83">Channel</a>(flow::log::Logger* logger_ptr, Channel_obj&amp;&amp; channel, Ctor_args&amp;&amp;... ctor_args);</div>
<div class="line"><a id="l00663" name="l00663"></a><span class="lineno">  663</span><span class="comment"></span> </div>
<div class="line"><a id="l00664" name="l00664"></a><span class="lineno">  664</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00665" name="l00665"></a><span class="lineno">  665</span><span class="comment">   * Invokes the destructor on the #Owned_channel.  In particular:</span></div>
<div class="line"><a id="l00666" name="l00666"></a><span class="lineno">  666</span><span class="comment">   *   - If the async_end_sending() async-handler is pending, it shall fire with</span></div>
<div class="line"><a id="l00667" name="l00667"></a><span class="lineno">  667</span><span class="comment">   *     transport::error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER, and the dtor shall return only once it</span></div>
<div class="line"><a id="l00668" name="l00668"></a><span class="lineno">  668</span><span class="comment">   *     has finished executing.</span></div>
<div class="line"><a id="l00669" name="l00669"></a><span class="lineno">  669</span><span class="comment">   *   - No other handler from `*this` shall fire.  (struc::Channel does not -- outside of async_end_sending(), a</span></div>
<div class="line"><a id="l00670" name="l00670"></a><span class="lineno">  670</span><span class="comment">   *     `transport::Channel`-level method -- follow the boost.asio-like one-off `async_*()` model.)</span></div>
<div class="line"><a id="l00671" name="l00671"></a><span class="lineno">  671</span><span class="comment">   *</span></div>
<div class="line"><a id="l00672" name="l00672"></a><span class="lineno">  672</span><span class="comment">   * Reminder: It is recommended, before invoking this destructor, to:</span></div>
<div class="line"><a id="l00673" name="l00673"></a><span class="lineno">  673</span><span class="comment">   *   - Call `async_end_sending(F)`.</span></div>
<div class="line"><a id="l00674" name="l00674"></a><span class="lineno">  674</span><span class="comment">   *   - Invoke this destructor once `F()` fires.</span></div>
<div class="line"><a id="l00675" name="l00675"></a><span class="lineno">  675</span><span class="comment">   *</span></div>
<div class="line"><a id="l00676" name="l00676"></a><span class="lineno">  676</span><span class="comment">   * See discussion in async_end_sending() doc header or shorter version in class doc header.</span></div>
<div class="line"><a id="l00677" name="l00677"></a><span class="lineno">  677</span><span class="comment">   */</span></div>
<div class="line"><a id="l00678" name="l00678"></a><span class="lineno">  678</span>  <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#abf9f4ae00258efb7a5d868a087658ffe">~Channel</a>();</div>
<div class="line"><a id="l00679" name="l00679"></a><span class="lineno">  679</span> </div>
<div class="line"><a id="l00680" name="l00680"></a><span class="lineno">  680</span>  <span class="comment">// Methods.</span></div>
<div class="line"><a id="l00681" name="l00681"></a><span class="lineno">  681</span><span class="comment"></span> </div>
<div class="line"><a id="l00682" name="l00682"></a><span class="lineno">  682</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00683" name="l00683"></a><span class="lineno">  683</span><span class="comment">   * Permanently memorizes the incoming-direction on-error handler, thus authorizing the emission of any</span></div>
<div class="line"><a id="l00684" name="l00684"></a><span class="lineno">  684</span><span class="comment">   * in-messages to handlers registered via expect_msg(), expect_msgs(), async_request() (as well as related handlers</span></div>
<div class="line"><a id="l00685" name="l00685"></a><span class="lineno">  685</span><span class="comment">   * set_unexpected_response_handler() and set_remote_unexpected_response_handler()).  Until this is invoked,</span></div>
<div class="line"><a id="l00686" name="l00686"></a><span class="lineno">  686</span><span class="comment">   * any incoming lower-level traffic is nevertheless saved in this process&#39;s user RAM (in fact inside the</span></div>
<div class="line"><a id="l00687" name="l00687"></a><span class="lineno">  687</span><span class="comment">   * #Owned_channel, though that&#39;s an implementation detail of sorts) to be emitted as required after start().</span></div>
<div class="line"><a id="l00688" name="l00688"></a><span class="lineno">  688</span><span class="comment">   *</span></div>
<div class="line"><a id="l00689" name="l00689"></a><span class="lineno">  689</span><span class="comment">   * @tparam Task_err</span></div>
<div class="line"><a id="l00690" name="l00690"></a><span class="lineno">  690</span><span class="comment">   *         Handler type matching signature of `flow::async::Task_asio_err`.</span></div>
<div class="line"><a id="l00691" name="l00691"></a><span class="lineno">  691</span><span class="comment">   * @param on_err_func</span></div>
<div class="line"><a id="l00692" name="l00692"></a><span class="lineno">  692</span><span class="comment">   *        The permanent on-channel-hosed error handler.  See class doc header for discussion of error semantics.</span></div>
<div class="line"><a id="l00693" name="l00693"></a><span class="lineno">  693</span><span class="comment">   * @return `true` on success; `false` if already start()ed, or if a prior error has</span></div>
<div class="line"><a id="l00694" name="l00694"></a><span class="lineno">  694</span><span class="comment">   *         hosed the owned transport::Channel (then no-op).</span></div>
<div class="line"><a id="l00695" name="l00695"></a><span class="lineno">  695</span><span class="comment">   */</span></div>
<div class="line"><a id="l00696" name="l00696"></a><span class="lineno">  696</span>  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> Task_err&gt;</div>
<div class="line"><a id="l00697" name="l00697"></a><span class="lineno">  697</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a33b4785c212ad88d8322fcc2f4369351">start</a>(Task_err&amp;&amp; on_err_func);</div>
<div class="line"><a id="l00698" name="l00698"></a><span class="lineno">  698</span><span class="comment"></span> </div>
<div class="line"><a id="l00699" name="l00699"></a><span class="lineno">  699</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00700" name="l00700"></a><span class="lineno">  700</span><span class="comment">   * Utility for use when #Builder_config template param is Heap_fixed_builder::Config,</span></div>
<div class="line"><a id="l00701" name="l00701"></a><span class="lineno">  701</span><span class="comment">   * this returns such a `Config` constructed with the most efficient yet safe values.</span></div>
<div class="line"><a id="l00702" name="l00702"></a><span class="lineno">  702</span><span class="comment">   * The resulting Heap_fixed_builder::Config, and the #Owned_channel `channel`, can then</span></div>
<div class="line"><a id="l00703" name="l00703"></a><span class="lineno">  703</span><span class="comment">   * be safely passed to the future struc::Channel&#39;s non-tag ctor form.</span></div>
<div class="line"><a id="l00704" name="l00704"></a><span class="lineno">  704</span><span class="comment">   *</span></div>
<div class="line"><a id="l00705" name="l00705"></a><span class="lineno">  705</span><span class="comment">   * ### Do not use this unless necessary ###</span></div>
<div class="line"><a id="l00706" name="l00706"></a><span class="lineno">  706</span><span class="comment">   * It is only necessary for advanced purposes, particularly if you choose to use a non-tag ctor form.</span></div>
<div class="line"><a id="l00707" name="l00707"></a><span class="lineno">  707</span><span class="comment">   * See the 1st non-tag ctor&#39;s doc header for when that might be.  Long story short, it is typically easier and</span></div>
<div class="line"><a id="l00708" name="l00708"></a><span class="lineno">  708</span><span class="comment">   * sufficient to use the Channel_base::Serialize_via_heap tag ctor.</span></div>
<div class="line"><a id="l00709" name="l00709"></a><span class="lineno">  709</span><span class="comment">   *</span></div>
<div class="line"><a id="l00710" name="l00710"></a><span class="lineno">  710</span><span class="comment">   * ### What about Heap_reader::Config counterpart? ###</span></div>
<div class="line"><a id="l00711" name="l00711"></a><span class="lineno">  711</span><span class="comment">   * See heap_reader_config().</span></div>
<div class="line"><a id="l00712" name="l00712"></a><span class="lineno">  712</span><span class="comment">   *</span></div>
<div class="line"><a id="l00713" name="l00713"></a><span class="lineno">  713</span><span class="comment">   * @param channel</span></div>
<div class="line"><a id="l00714" name="l00714"></a><span class="lineno">  714</span><span class="comment">   *        The channel you plan to pass as `channel` into struc::Channel ctor.</span></div>
<div class="line"><a id="l00715" name="l00715"></a><span class="lineno">  715</span><span class="comment">   *        Note `channel.get_logger()` is supplied as the `Logger` to the returned `Config`.</span></div>
<div class="line"><a id="l00716" name="l00716"></a><span class="lineno">  716</span><span class="comment">   *        Behavior is undefined (assertion may trip) if `channel` is not transport::Channel::initialized().</span></div>
<div class="line"><a id="l00717" name="l00717"></a><span class="lineno">  717</span><span class="comment">   *        Behavior is undefined if `channel` is not in PEER state.</span></div>
<div class="line"><a id="l00718" name="l00718"></a><span class="lineno">  718</span><span class="comment">   * @return See above.</span></div>
<div class="line"><a id="l00719" name="l00719"></a><span class="lineno">  719</span><span class="comment">   */</span></div>
<div class="line"><a id="l00720" name="l00720"></a><span class="lineno">  720</span>  <span class="keyword">static</span> <a class="code hl_struct" href="structipc_1_1transport_1_1struc_1_1Heap__fixed__builder_1_1Config.html">Heap_fixed_builder::Config</a> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a08062e4cc99347e94e9e917b382985ee">heap_fixed_builder_config</a>(<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4a0188052c15cab70d712f41b0e74ba7">Owned_channel</a>&amp; channel);</div>
<div class="line"><a id="l00721" name="l00721"></a><span class="lineno">  721</span><span class="comment"></span> </div>
<div class="line"><a id="l00722" name="l00722"></a><span class="lineno">  722</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00723" name="l00723"></a><span class="lineno">  723</span><span class="comment">   * Deserializing counterpart to heap_fixed_builder_config().  It is mostly provided for consistency,</span></div>
<div class="line"><a id="l00724" name="l00724"></a><span class="lineno">  724</span><span class="comment">   * as it simply returns `Heap_reader::Config(channel.get_logger())`.</span></div>
<div class="line"><a id="l00725" name="l00725"></a><span class="lineno">  725</span><span class="comment">   *</span></div>
<div class="line"><a id="l00726" name="l00726"></a><span class="lineno">  726</span><span class="comment">   * @param channel</span></div>
<div class="line"><a id="l00727" name="l00727"></a><span class="lineno">  727</span><span class="comment">   *        See heap_fixed_builder_config().</span></div>
<div class="line"><a id="l00728" name="l00728"></a><span class="lineno">  728</span><span class="comment">   * @return See above.</span></div>
<div class="line"><a id="l00729" name="l00729"></a><span class="lineno">  729</span><span class="comment">   */</span></div>
<div class="line"><a id="l00730" name="l00730"></a><span class="lineno">  730</span>  <span class="keyword">static</span> <a class="code hl_struct" href="structipc_1_1transport_1_1struc_1_1Heap__reader_1_1Config.html">Heap_reader::Config</a> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a629c06957e1c5fac96d62473f7e18966">heap_reader_config</a>(<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4a0188052c15cab70d712f41b0e74ba7">Owned_channel</a>&amp; channel);</div>
<div class="line"><a id="l00731" name="l00731"></a><span class="lineno">  731</span><span class="comment"></span> </div>
<div class="line"><a id="l00732" name="l00732"></a><span class="lineno">  732</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00733" name="l00733"></a><span class="lineno">  733</span><span class="comment">   * Returns the (light-weight) #Builder_config specified (directly or indirectly) at construction</span></div>
<div class="line"><a id="l00734" name="l00734"></a><span class="lineno">  734</span><span class="comment">   * time.  Informally: in particular this could be used to generate a `Builder_config::Builder` to fill out</span></div>
<div class="line"><a id="l00735" name="l00735"></a><span class="lineno">  735</span><span class="comment">   * manually via Struct_builder::payload_msg_builder() (a direct #Capnp_msg_builder_interface), without yet specifying</span></div>
<div class="line"><a id="l00736" name="l00736"></a><span class="lineno">  736</span><span class="comment">   * any schema, and eventually `move()` into a new #Msg_out, via the Msg_out 2nd/advanced ctor form.</span></div>
<div class="line"><a id="l00737" name="l00737"></a><span class="lineno">  737</span><span class="comment">   *</span></div>
<div class="line"><a id="l00738" name="l00738"></a><span class="lineno">  738</span><span class="comment">   * Tip: If you lack a `*this` from which to invoke struct_builder_config(), you may be able to cheaply generate</span></div>
<div class="line"><a id="l00739" name="l00739"></a><span class="lineno">  739</span><span class="comment">   * a #Builder_config via session::Session impls&#39; methods (e.g., session::Session_mv::heap_fixed_builder_config(),</span></div>
<div class="line"><a id="l00740" name="l00740"></a><span class="lineno">  740</span><span class="comment">   * session::shm::classic::Session_mv::app_shm_builder_config(), etc.).</span></div>
<div class="line"><a id="l00741" name="l00741"></a><span class="lineno">  741</span><span class="comment">   *</span></div>
<div class="line"><a id="l00742" name="l00742"></a><span class="lineno">  742</span><span class="comment">   * @return See above.</span></div>
<div class="line"><a id="l00743" name="l00743"></a><span class="lineno">  743</span><span class="comment">   */</span></div>
<div class="line"><a id="l00744" name="l00744"></a><span class="lineno">  744</span>  <span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a346752b515926a2938ed2adb9de92b1e">Builder_config</a>&amp; <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a969bc2021565c542c902fc14ff711c38">struct_builder_config</a>() <span class="keyword">const</span>;</div>
<div class="line"><a id="l00745" name="l00745"></a><span class="lineno">  745</span><span class="comment"></span> </div>
<div class="line"><a id="l00746" name="l00746"></a><span class="lineno">  746</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00747" name="l00747"></a><span class="lineno">  747</span><span class="comment">   * Returns reference to immutable `Builder_config::Builder::Session` (a light-weight value, as of this writing</span></div>
<div class="line"><a id="l00748" name="l00748"></a><span class="lineno">  748</span><span class="comment">   * at most a pointer) specified (directly or indirectly) at construction time.  See that ctor argument&#39;s docs;</span></div>
<div class="line"><a id="l00749" name="l00749"></a><span class="lineno">  749</span><span class="comment">   * the arg is also named `struct_lender_session`.</span></div>
<div class="line"><a id="l00750" name="l00750"></a><span class="lineno">  750</span><span class="comment">   *</span></div>
<div class="line"><a id="l00751" name="l00751"></a><span class="lineno">  751</span><span class="comment">   * @return See above.</span></div>
<div class="line"><a id="l00752" name="l00752"></a><span class="lineno">  752</span><span class="comment">   */</span></div>
<div class="line"><a id="l00753" name="l00753"></a><span class="lineno">  753</span>  <span class="keyword">const</span> <span class="keyword">typename</span> Builder_config::Builder::Session&amp; <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#ade98da21ce433f8ba338e3139760e94a">struct_lender_session</a>() <span class="keyword">const</span>;</div>
<div class="line"><a id="l00754" name="l00754"></a><span class="lineno">  754</span><span class="comment"></span> </div>
<div class="line"><a id="l00755" name="l00755"></a><span class="lineno">  755</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00756" name="l00756"></a><span class="lineno">  756</span><span class="comment">   * Deserializing counterpart to struct_builder_config().</span></div>
<div class="line"><a id="l00757" name="l00757"></a><span class="lineno">  757</span><span class="comment">   * @return See above.</span></div>
<div class="line"><a id="l00758" name="l00758"></a><span class="lineno">  758</span><span class="comment">   */</span></div>
<div class="line"><a id="l00759" name="l00759"></a><span class="lineno">  759</span>  <span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ad3ff78f00b7f230562d713ec6cf8499c">Reader_config</a>&amp; <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#ade9a8f99615d2c53de1a68989376750d">struct_reader_config</a>() <span class="keyword">const</span>;</div>
<div class="line"><a id="l00760" name="l00760"></a><span class="lineno">  760</span><span class="comment"></span> </div>
<div class="line"><a id="l00761" name="l00761"></a><span class="lineno">  761</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00762" name="l00762"></a><span class="lineno">  762</span><span class="comment">   * Access to immutable transport::Channel moved-into `*this` at construction.</span></div>
<div class="line"><a id="l00763" name="l00763"></a><span class="lineno">  763</span><span class="comment">   * @return See above.</span></div>
<div class="line"><a id="l00764" name="l00764"></a><span class="lineno">  764</span><span class="comment">   */</span></div>
<div class="line"><a id="l00765" name="l00765"></a><span class="lineno">  765</span>  <span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4a0188052c15cab70d712f41b0e74ba7">Owned_channel</a>&amp; <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a1d0225edcfe5f000f26787d5fa5f6821">owned_channel</a>() <span class="keyword">const</span>;</div>
<div class="line"><a id="l00766" name="l00766"></a><span class="lineno">  766</span><span class="comment"></span> </div>
<div class="line"><a id="l00767" name="l00767"></a><span class="lineno">  767</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00768" name="l00768"></a><span class="lineno">  768</span><span class="comment">   * Access to mutable transport::Channel moved-into `*this` at construction.</span></div>
<div class="line"><a id="l00769" name="l00769"></a><span class="lineno">  769</span><span class="comment">   *</span></div>
<div class="line"><a id="l00770" name="l00770"></a><span class="lineno">  770</span><span class="comment">   * Formally only the following non-`const` methods of the returned pointee may be accessed:</span></div>
<div class="line"><a id="l00771" name="l00771"></a><span class="lineno">  771</span><span class="comment">   *   - transport::Channel::auto_ping();</span></div>
<div class="line"><a id="l00772" name="l00772"></a><span class="lineno">  772</span><span class="comment">   *   - transport::Channel::idle_timer_run().</span></div>
<div class="line"><a id="l00773" name="l00773"></a><span class="lineno">  773</span><span class="comment">   *</span></div>
<div class="line"><a id="l00774" name="l00774"></a><span class="lineno">  774</span><span class="comment">   * Informally: those are both safe and potentially useful.  Since #Owned_channel is `sync_io`-core-bearing,</span></div>
<div class="line"><a id="l00775" name="l00775"></a><span class="lineno">  775</span><span class="comment">   * to invoke either of those directly on the `Channel` *before* subsuming it into `*this` ctor, one would have</span></div>
<div class="line"><a id="l00776" name="l00776"></a><span class="lineno">  776</span><span class="comment">   * to do `Channel::start_*_ops()`; but `*this` ctor requires a fresh #Owned_channel without such setup having</span></div>
<div class="line"><a id="l00777" name="l00777"></a><span class="lineno">  777</span><span class="comment">   * been performed.  Catch-22!  However, with the availability of owned_channel_mutable(), one can simply call them</span></div>
<div class="line"><a id="l00778" name="l00778"></a><span class="lineno">  778</span><span class="comment">   * via `this-&gt;owned_channel_mutable-&gt;...()` and move on.</span></div>
<div class="line"><a id="l00779" name="l00779"></a><span class="lineno">  779</span><span class="comment">   *</span></div>
<div class="line"><a id="l00780" name="l00780"></a><span class="lineno">  780</span><span class="comment">   * Informally: any other use = at your own risk.  It may interfere with our operations =&gt; undefined behavior.</span></div>
<div class="line"><a id="l00781" name="l00781"></a><span class="lineno">  781</span><span class="comment">   *</span></div>
<div class="line"><a id="l00782" name="l00782"></a><span class="lineno">  782</span><span class="comment">   * @see async_end_sending().</span></div>
<div class="line"><a id="l00783" name="l00783"></a><span class="lineno">  783</span><span class="comment">   *</span></div>
<div class="line"><a id="l00784" name="l00784"></a><span class="lineno">  784</span><span class="comment">   * @todo Consider adding `struc::Channel::auto_ping()` and `struc::Channel::idle_timer_run()` and, for safety,</span></div>
<div class="line"><a id="l00785" name="l00785"></a><span class="lineno">  785</span><span class="comment">   * removing struc::Channel::owned_channel_mutable().</span></div>
<div class="line"><a id="l00786" name="l00786"></a><span class="lineno">  786</span><span class="comment">   *</span></div>
<div class="line"><a id="l00787" name="l00787"></a><span class="lineno">  787</span><span class="comment">   * @return See above.  Not null.</span></div>
<div class="line"><a id="l00788" name="l00788"></a><span class="lineno">  788</span><span class="comment">   */</span></div>
<div class="line"><a id="l00789" name="l00789"></a><span class="lineno">  789</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4a0188052c15cab70d712f41b0e74ba7">Owned_channel</a>* <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#af9130e43dc985fca4a41f19581048b51">owned_channel_mutable</a>();</div>
<div class="line"><a id="l00790" name="l00790"></a><span class="lineno">  790</span><span class="comment"></span> </div>
<div class="line"><a id="l00791" name="l00791"></a><span class="lineno">  791</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00792" name="l00792"></a><span class="lineno">  792</span><span class="comment">   * Returns the (non-nil) logged-in session token; or nil if not in logged-in phase, or if a prior error has</span></div>
<div class="line"><a id="l00793" name="l00793"></a><span class="lineno">  793</span><span class="comment">   * hosed the owned transport::Channel.</span></div>
<div class="line"><a id="l00794" name="l00794"></a><span class="lineno">  794</span><span class="comment">   *</span></div>
<div class="line"><a id="l00795" name="l00795"></a><span class="lineno">  795</span><span class="comment">   * Informally: If `*this` is the session master channel, then: Outside of, perhaps, logging/reporting, it</span></div>
<div class="line"><a id="l00796" name="l00796"></a><span class="lineno">  796</span><span class="comment">   * should not be necessary to call this.</span></div>
<div class="line"><a id="l00797" name="l00797"></a><span class="lineno">  797</span><span class="comment">   *</span></div>
<div class="line"><a id="l00798" name="l00798"></a><span class="lineno">  798</span><span class="comment">   * @return See above.  Note: The reference returned is always one of 2: a certain unspecified internal</span></div>
<div class="line"><a id="l00799" name="l00799"></a><span class="lineno">  799</span><span class="comment">   *         item, or to transport::struc::NULL_SESSION_TOKEN.</span></div>
<div class="line"><a id="l00800" name="l00800"></a><span class="lineno">  800</span><span class="comment">   */</span></div>
<div class="line"><a id="l00801" name="l00801"></a><span class="lineno">  801</span>  <span class="keyword">const</span> <a class="code hl_typedef" href="namespaceipc_1_1transport_1_1struc.html#a6751c05fb6582a34c7c47ac470c4a48b">Session_token</a>&amp; <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a9a540a274df3bc7da8fc35ed2a2c1e57">session_token</a>() <span class="keyword">const</span>;</div>
<div class="line"><a id="l00802" name="l00802"></a><span class="lineno">  802</span><span class="comment"></span> </div>
<div class="line"><a id="l00803" name="l00803"></a><span class="lineno">  803</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00804" name="l00804"></a><span class="lineno">  804</span><span class="comment">   * Creates/returns empty out-message, optionally also holding a native handle,</span></div>
<div class="line"><a id="l00805" name="l00805"></a><span class="lineno">  805</span><span class="comment">   * to mutate and later send() (et al).  Alternatively you may simply directly construct a #Msg_out;</span></div>
<div class="line"><a id="l00806" name="l00806"></a><span class="lineno">  806</span><span class="comment">   * create_msg() is only syntactic sugar, since `*this` memorizes the builder engine and will pass-it-through</span></div>
<div class="line"><a id="l00807" name="l00807"></a><span class="lineno">  807</span><span class="comment">   * to the aforementioned constructor.</span></div>
<div class="line"><a id="l00808" name="l00808"></a><span class="lineno">  808</span><span class="comment">   *</span></div>
<div class="line"><a id="l00809" name="l00809"></a><span class="lineno">  809</span><span class="comment">   * @see &quot;Lifecycle of an out-message&quot; section of this class&#39;s doc header.</span></div>
<div class="line"><a id="l00810" name="l00810"></a><span class="lineno">  810</span><span class="comment">   *</span></div>
<div class="line"><a id="l00811" name="l00811"></a><span class="lineno">  811</span><span class="comment">   * @note The decision as to whether the returned message is unsolicited or a response to an in-message shall</span></div>
<div class="line"><a id="l00812" name="l00812"></a><span class="lineno">  812</span><span class="comment">   *       be indicated at send() (et al) time via its `originating_msg_or_null` arg.</span></div>
<div class="line"><a id="l00813" name="l00813"></a><span class="lineno">  813</span><span class="comment">   *</span></div>
<div class="line"><a id="l00814" name="l00814"></a><span class="lineno">  814</span><span class="comment">   * @param hndl_or_null</span></div>
<div class="line"><a id="l00815" name="l00815"></a><span class="lineno">  815</span><span class="comment">   *        The native handle to pair with the structured message; or default-cted (null) handle to</span></div>
<div class="line"><a id="l00816" name="l00816"></a><span class="lineno">  816</span><span class="comment">   *        pair no such thing.  It becomes `.null()` -- `*this` is in charge of returning it to</span></div>
<div class="line"><a id="l00817" name="l00817"></a><span class="lineno">  817</span><span class="comment">   *        OS at the proper time.  You may use `dup()` in a Unix-like OS, if you want to keep a functioning</span></div>
<div class="line"><a id="l00818" name="l00818"></a><span class="lineno">  818</span><span class="comment">   *        handle (FD) locally.</span></div>
<div class="line"><a id="l00819" name="l00819"></a><span class="lineno">  819</span><span class="comment">   * @return The new out-message payload, blank to start.  Note #Msg_out is cheaply move-assignable and</span></div>
<div class="line"><a id="l00820" name="l00820"></a><span class="lineno">  820</span><span class="comment">   *         move-constructible (but not copyable).</span></div>
<div class="line"><a id="l00821" name="l00821"></a><span class="lineno">  821</span><span class="comment">   */</span></div>
<div class="line"><a id="l00822" name="l00822"></a><span class="lineno">  822</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">Msg_out</a> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a394e0f9cfa5f9bd4ba9ee17d3d54a8b3">create_msg</a>(<a class="code hl_struct" href="structipc_1_1util_1_1Native__handle.html">Native_handle</a>&amp;&amp; hndl_or_null = <a class="code hl_typedef" href="namespaceipc_1_1transport.html#a7ee4551983d9df16ec16a3139bac50e8">Native_handle</a>()) <span class="keyword">const</span>;</div>
<div class="line"><a id="l00823" name="l00823"></a><span class="lineno">  823</span><span class="comment"></span> </div>
<div class="line"><a id="l00824" name="l00824"></a><span class="lineno">  824</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00825" name="l00825"></a><span class="lineno">  825</span><span class="comment">   * Registers the expectation of up to 1 *notification* in-message whose #Msg_which equals `which`.</span></div>
<div class="line"><a id="l00826" name="l00826"></a><span class="lineno">  826</span><span class="comment">   * No-op and return `false` if `which` is already being expected, if log-in phase is not yet completed, or if</span></div>
<div class="line"><a id="l00827" name="l00827"></a><span class="lineno">  827</span><span class="comment">   * a prior error has hosed the owned transport::Channel.</span></div>
<div class="line"><a id="l00828" name="l00828"></a><span class="lineno">  828</span><span class="comment">   *</span></div>
<div class="line"><a id="l00829" name="l00829"></a><span class="lineno">  829</span><span class="comment">   * The expectation is unregistered upon receipt of the applicable in-message (and firing it with that in-message</span></div>
<div class="line"><a id="l00830" name="l00830"></a><span class="lineno">  830</span><span class="comment">   * #Msg_in_ptr as arg).</span></div>
<div class="line"><a id="l00831" name="l00831"></a><span class="lineno">  831</span><span class="comment">   *</span></div>
<div class="line"><a id="l00832" name="l00832"></a><span class="lineno">  832</span><span class="comment">   * @tparam On_msg_handler</span></div>
<div class="line"><a id="l00833" name="l00833"></a><span class="lineno">  833</span><span class="comment">   *         Handler type for in-messages; see class doc header for in-message handling signature.</span></div>
<div class="line"><a id="l00834" name="l00834"></a><span class="lineno">  834</span><span class="comment">   * @param which</span></div>
<div class="line"><a id="l00835" name="l00835"></a><span class="lineno">  835</span><span class="comment">   *        Top-level #Msg_body union `which()` value to expect.</span></div>
<div class="line"><a id="l00836" name="l00836"></a><span class="lineno">  836</span><span class="comment">   * @param on_msg_func</span></div>
<div class="line"><a id="l00837" name="l00837"></a><span class="lineno">  837</span><span class="comment">   *        `on_msg_func(M)` shall be invoked in the manner explained in class doc header,</span></div>
<div class="line"><a id="l00838" name="l00838"></a><span class="lineno">  838</span><span class="comment">   *        on receipt of message with `which() == which`.</span></div>
<div class="line"><a id="l00839" name="l00839"></a><span class="lineno">  839</span><span class="comment">   * @return `true` on success; `false` due to one of the above conditions.</span></div>
<div class="line"><a id="l00840" name="l00840"></a><span class="lineno">  840</span><span class="comment">   */</span></div>
<div class="line"><a id="l00841" name="l00841"></a><span class="lineno">  841</span>  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_msg_handler&gt;</div>
<div class="line"><a id="l00842" name="l00842"></a><span class="lineno">  842</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a160a8d49624f15a2596ee7b0244584b0">expect_msg</a>(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">Msg_which_in</a> which, On_msg_handler&amp;&amp; on_msg_func);</div>
<div class="line"><a id="l00843" name="l00843"></a><span class="lineno">  843</span><span class="comment"></span> </div>
<div class="line"><a id="l00844" name="l00844"></a><span class="lineno">  844</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00845" name="l00845"></a><span class="lineno">  845</span><span class="comment">   * Registers the expectation of 0+ *notification* in-messages whose #Msg_which equals `which`.</span></div>
<div class="line"><a id="l00846" name="l00846"></a><span class="lineno">  846</span><span class="comment">   * No-op and return `false` if `which` is already being expected, if log-in phase is not yet completed, or if</span></div>
<div class="line"><a id="l00847" name="l00847"></a><span class="lineno">  847</span><span class="comment">   * a prior error has hosed the owned transport::Channel.</span></div>
<div class="line"><a id="l00848" name="l00848"></a><span class="lineno">  848</span><span class="comment">   *</span></div>
<div class="line"><a id="l00849" name="l00849"></a><span class="lineno">  849</span><span class="comment">   * The expectation is unregistered upon subsequent `undo_expect_msgs(which)`.</span></div>
<div class="line"><a id="l00850" name="l00850"></a><span class="lineno">  850</span><span class="comment">   *</span></div>
<div class="line"><a id="l00851" name="l00851"></a><span class="lineno">  851</span><span class="comment">   * @tparam On_msg_handler</span></div>
<div class="line"><a id="l00852" name="l00852"></a><span class="lineno">  852</span><span class="comment">   *         See expect_msg().</span></div>
<div class="line"><a id="l00853" name="l00853"></a><span class="lineno">  853</span><span class="comment">   * @param which</span></div>
<div class="line"><a id="l00854" name="l00854"></a><span class="lineno">  854</span><span class="comment">   *        See expect_msg().</span></div>
<div class="line"><a id="l00855" name="l00855"></a><span class="lineno">  855</span><span class="comment">   * @param on_msg_func</span></div>
<div class="line"><a id="l00856" name="l00856"></a><span class="lineno">  856</span><span class="comment">   *        See expect_msg().</span></div>
<div class="line"><a id="l00857" name="l00857"></a><span class="lineno">  857</span><span class="comment">   * @return See expect_msg().</span></div>
<div class="line"><a id="l00858" name="l00858"></a><span class="lineno">  858</span><span class="comment">   */</span></div>
<div class="line"><a id="l00859" name="l00859"></a><span class="lineno">  859</span>  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_msg_handler&gt;</div>
<div class="line"><a id="l00860" name="l00860"></a><span class="lineno">  860</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a3376b821b129ca3847484a178e080c67">expect_msgs</a>(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">Msg_which_in</a> which, On_msg_handler&amp;&amp; on_msg_func);</div>
<div class="line"><a id="l00861" name="l00861"></a><span class="lineno">  861</span><span class="comment"></span> </div>
<div class="line"><a id="l00862" name="l00862"></a><span class="lineno">  862</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00863" name="l00863"></a><span class="lineno">  863</span><span class="comment">   * Unregisters the expectation earlier-registered with expect_msgs().</span></div>
<div class="line"><a id="l00864" name="l00864"></a><span class="lineno">  864</span><span class="comment">   * No-op and return `false` if `which` is not being expected via expect_msgs(), if log-in phase is not yet</span></div>
<div class="line"><a id="l00865" name="l00865"></a><span class="lineno">  865</span><span class="comment">   * completed, or if a prior error has hosed the owned transport::Channel.</span></div>
<div class="line"><a id="l00866" name="l00866"></a><span class="lineno">  866</span><span class="comment">   *</span></div>
<div class="line"><a id="l00867" name="l00867"></a><span class="lineno">  867</span><span class="comment">   * @param which</span></div>
<div class="line"><a id="l00868" name="l00868"></a><span class="lineno">  868</span><span class="comment">   *        See expect_msgs().</span></div>
<div class="line"><a id="l00869" name="l00869"></a><span class="lineno">  869</span><span class="comment">   * @return See above.</span></div>
<div class="line"><a id="l00870" name="l00870"></a><span class="lineno">  870</span><span class="comment">   */</span></div>
<div class="line"><a id="l00871" name="l00871"></a><span class="lineno">  871</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a896bb326a58f433bade75b62f1893462">undo_expect_msgs</a>(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">Msg_which_in</a> which);</div>
<div class="line"><a id="l00872" name="l00872"></a><span class="lineno">  872</span><span class="comment"></span> </div>
<div class="line"><a id="l00873" name="l00873"></a><span class="lineno">  873</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00874" name="l00874"></a><span class="lineno">  874</span><span class="comment">   * In the synchronous/non-blocking manner of Blob_sender::send_blob() or Native_handle_sender::send_native_handle()</span></div>
<div class="line"><a id="l00875" name="l00875"></a><span class="lineno">  875</span><span class="comment">   * sends the given message to the opposing peer, as a *notification* (without expecting response).</span></div>
<div class="line"><a id="l00876" name="l00876"></a><span class="lineno">  876</span><span class="comment">   * The message may contain a #Native_handle.</span></div>
<div class="line"><a id="l00877" name="l00877"></a><span class="lineno">  877</span><span class="comment">   *</span></div>
<div class="line"><a id="l00878" name="l00878"></a><span class="lineno">  878</span><span class="comment">   * send() shall no-op (and return `false`) if one of the following is true.</span></div>
<div class="line"><a id="l00879" name="l00879"></a><span class="lineno">  879</span><span class="comment">   *   - Log-in phase, as a client, has not yet been completed.</span></div>
<div class="line"><a id="l00880" name="l00880"></a><span class="lineno">  880</span><span class="comment">   *     Use the other form of send() instead, as a log-in response (to the log-in request `msg`) is required.</span></div>
<div class="line"><a id="l00881" name="l00881"></a><span class="lineno">  881</span><span class="comment">   *   - Log-in phase, as a server, has not yet been completed, and `originating_msg_or_null` is null.</span></div>
<div class="line"><a id="l00882" name="l00882"></a><span class="lineno">  882</span><span class="comment">   *     Use non-null instead.</span></div>
<div class="line"><a id="l00883" name="l00883"></a><span class="lineno">  883</span><span class="comment">   *</span></div>
<div class="line"><a id="l00884" name="l00884"></a><span class="lineno">  884</span><span class="comment">   * Further documentation of behavior shall assume this no-op condition is not the case.</span></div>
<div class="line"><a id="l00885" name="l00885"></a><span class="lineno">  885</span><span class="comment">   *</span></div>
<div class="line"><a id="l00886" name="l00886"></a><span class="lineno">  886</span><span class="comment">   * @see async_request() overload which sends a *request* (same thing as here but *with* expecting response(s)).</span></div>
<div class="line"><a id="l00887" name="l00887"></a><span class="lineno">  887</span><span class="comment">   *</span></div>
<div class="line"><a id="l00888" name="l00888"></a><span class="lineno">  888</span><span class="comment">   * @note You may use this in logged-in phase; or in logging-in phase, as a server.</span></div>
<div class="line"><a id="l00889" name="l00889"></a><span class="lineno">  889</span><span class="comment">   *</span></div>
<div class="line"><a id="l00890" name="l00890"></a><span class="lineno">  890</span><span class="comment">   * ### Send mechanics (applies also to async_request() and sync_request()) ###</span></div>
<div class="line"><a id="l00891" name="l00891"></a><span class="lineno">  891</span><span class="comment">   * The purpose of this important method is hopefully clear.  That it&#39;s, essentially, a wrapper for</span></div>
<div class="line"><a id="l00892" name="l00892"></a><span class="lineno">  892</span><span class="comment">   * one of the aforementioned transport::Channel methods is also probably obvious.  However its error-reporting</span></div>
<div class="line"><a id="l00893" name="l00893"></a><span class="lineno">  893</span><span class="comment">   * semantics are somewhat different from transport::Channel and the `Blob_sender`/`Native_handle_sender` concept(s) it</span></div>
<div class="line"><a id="l00894" name="l00894"></a><span class="lineno">  894</span><span class="comment">   * implements.  Long story short, it reports errors similarly to the core Blob_sender::send_blob() or</span></div>
<div class="line"><a id="l00895" name="l00895"></a><span class="lineno">  895</span><span class="comment">   * Native_handle_sender::send_native_handle() with the following differences:</span></div>
<div class="line"><a id="l00896" name="l00896"></a><span class="lineno">  896</span><span class="comment">   *   - If `msg` contains a #Native_handle, but #Owned_channel has no native-handles pipe: no-op, return `false`.</span></div>
<div class="line"><a id="l00897" name="l00897"></a><span class="lineno">  897</span><span class="comment">   *   - If called after async_end_sending(): no-op, return `false`.</span></div>
<div class="line"><a id="l00898" name="l00898"></a><span class="lineno">  898</span><span class="comment">   *   - If called after a background receive or preceding send() / async_request() / sync_request() emitted error:</span></div>
<div class="line"><a id="l00899" name="l00899"></a><span class="lineno">  899</span><span class="comment">   *     no-op, return `false`.</span></div>
<div class="line"><a id="l00900" name="l00900"></a><span class="lineno">  900</span><span class="comment">   *   - Otherwise it&#39;ll attempt the core `send_*()` and return `true`.</span></div>
<div class="line"><a id="l00901" name="l00901"></a><span class="lineno">  901</span><span class="comment">   *     - If that is successful, send() is successful.</span></div>
<div class="line"><a id="l00902" name="l00902"></a><span class="lineno">  902</span><span class="comment">   *     - If not -- if it emitted error E -- then send() emits error E.</span></div>
<div class="line"><a id="l00903" name="l00903"></a><span class="lineno">  903</span><span class="comment">   *       - And `*this` shall be considered hosed for any subsequent transmission.</span></div>
<div class="line"><a id="l00904" name="l00904"></a><span class="lineno">  904</span><span class="comment">   *</span></div>
<div class="line"><a id="l00905" name="l00905"></a><span class="lineno">  905</span><span class="comment">   * ### In more detail (applies also to async_request() and sync_request()) ###</span></div>
<div class="line"><a id="l00906" name="l00906"></a><span class="lineno">  906</span><span class="comment">   * Here is what the method does, ignoring logged-in phase checks and potential change inside.</span></div>
<div class="line"><a id="l00907" name="l00907"></a><span class="lineno">  907</span><span class="comment">   *   -# If `msg` contains a #Native_handle, but Channel::S_HAS_BLOB_PIPE_ONLY is `true`, then returns `false`</span></div>
<div class="line"><a id="l00908" name="l00908"></a><span class="lineno">  908</span><span class="comment">   *      and otherwise no-ops.  This is a misuse of the chosen #Owned_channel as configured: a handles pipe</span></div>
<div class="line"><a id="l00909" name="l00909"></a><span class="lineno">  909</span><span class="comment">   *      is required to send handles.  Else:</span></div>
<div class="line"><a id="l00910" name="l00910"></a><span class="lineno">  910</span><span class="comment">   *   -# Checks whether the pipe is hosed by a preceding error (which would have been reported via the</span></div>
<div class="line"><a id="l00911" name="l00911"></a><span class="lineno">  911</span><span class="comment">   *      on-error handler registered by user on `*this`; or by the previous `send()`/etc. synchronously, if that&#39;s what</span></div>
<div class="line"><a id="l00912" name="l00912"></a><span class="lineno">  912</span><span class="comment">   *      discovered the pipe is hosed instead).  If so returns `false` and otherwise no-ops.  Else:</span></div>
<div class="line"><a id="l00913" name="l00913"></a><span class="lineno">  913</span><span class="comment">   *      (Note the previously discovered/emitted #Error_code is not re-emitted this time.)  Else:</span></div>
<div class="line"><a id="l00914" name="l00914"></a><span class="lineno">  914</span><span class="comment">   *   -# If you&#39;ve called async_end_sending() already: Returns `false` and otherwise no-ops.  Else:</span></div>
<div class="line"><a id="l00915" name="l00915"></a><span class="lineno">  915</span><span class="comment">   *   -# Invokes either `Owned_channel::send_blob()` or `Owned_channel::send_native_handle()` 1+ times.</span></div>
<div class="line"><a id="l00916" name="l00916"></a><span class="lineno">  916</span><span class="comment">   *      (If Channel::S_HAS_BLOB_PIPE_ONLY: the former.  If Channel::S_HAS_NATIVE_HANDLE_PIPE_ONLY: the latter,</span></div>
<div class="line"><a id="l00917" name="l00917"></a><span class="lineno">  917</span><span class="comment">   *      even if `msg` stores no #Native_handle (it&#39;s not required to send a handle).  If Channel::S_HAS_2_PIPES:</span></div>
<div class="line"><a id="l00918" name="l00918"></a><span class="lineno">  918</span><span class="comment">   *      the latter or the former depending on whether `msg` stores a #Native_handle.)</span></div>
<div class="line"><a id="l00919" name="l00919"></a><span class="lineno">  919</span><span class="comment">   *      This determines the possible #Error_code emitted; see doc header for the chosen</span></div>
<div class="line"><a id="l00920" name="l00920"></a><span class="lineno">  920</span><span class="comment">   *      sender concept impls for #Owned_channel.  However:</span></div>
<div class="line"><a id="l00921" name="l00921"></a><span class="lineno">  921</span><span class="comment">   *      - Note: transport::error::Code::S_SENDS_FINISHED_CANNOT_SEND shall not be emitted; instead send() will return</span></div>
<div class="line"><a id="l00922" name="l00922"></a><span class="lineno">  922</span><span class="comment">   *        `false` as noted above.</span></div>
<div class="line"><a id="l00923" name="l00923"></a><span class="lineno">  923</span><span class="comment">   *      - Note: Since we are in charge, internally, of invoking the low-level `send_*()` method, we shall ensure</span></div>
<div class="line"><a id="l00924" name="l00924"></a><span class="lineno">  924</span><span class="comment">   *        transport::error::Code::S_INVALID_ARGUMENT is not a possibility.</span></div>
<div class="line"><a id="l00925" name="l00925"></a><span class="lineno">  925</span><span class="comment">   *      - Serialization errors are also possible (can be thought of similarly to `send_*()` failing).</span></div>
<div class="line"><a id="l00926" name="l00926"></a><span class="lineno">  926</span><span class="comment">   *   -# If such a call emits an error, the present method shall forward (emit) that error (but return `true`).</span></div>
<div class="line"><a id="l00927" name="l00927"></a><span class="lineno">  927</span><span class="comment">   *      Moreover the pipe shall be considered hosed:</span></div>
<div class="line"><a id="l00928" name="l00928"></a><span class="lineno">  928</span><span class="comment">   *      - The triggering #Error_code will *not* be emitted to user via on-error handler registered on `*this`,</span></div>
<div class="line"><a id="l00929" name="l00929"></a><span class="lineno">  929</span><span class="comment">   *        because it will be emitted to the caller synchronously here by send().</span></div>
<div class="line"><a id="l00930" name="l00930"></a><span class="lineno">  930</span><span class="comment">   *      - No futher on-in-message user handlers (such as from expect_msg()) shall fire.</span></div>
<div class="line"><a id="l00931" name="l00931"></a><span class="lineno">  931</span><span class="comment">   *      - Any future transmission API calls will no-op indicating this in various ways:</span></div>
<div class="line"><a id="l00932" name="l00932"></a><span class="lineno">  932</span><span class="comment">   *        - expect_msg(), expect_msgs(), `set_*_handler()` shall return `false`;</span></div>
<div class="line"><a id="l00933" name="l00933"></a><span class="lineno">  933</span><span class="comment">   *        - `create_*()` shall return null;</span></div>
<div class="line"><a id="l00934" name="l00934"></a><span class="lineno">  934</span><span class="comment">   *        - send() shall return `false` (as noted above).</span></div>
<div class="line"><a id="l00935" name="l00935"></a><span class="lineno">  935</span><span class="comment">   *   -# Otherwise, cool.  It shall return `true` and not emit a truthy #Error_code.</span></div>
<div class="line"><a id="l00936" name="l00936"></a><span class="lineno">  936</span><span class="comment">   *</span></div>
<div class="line"><a id="l00937" name="l00937"></a><span class="lineno">  937</span><span class="comment">   * @see async_end_sending() for properly flushing out-messages near the end of `*this` lifetime.</span></div>
<div class="line"><a id="l00938" name="l00938"></a><span class="lineno">  938</span><span class="comment">   *</span></div>
<div class="line"><a id="l00939" name="l00939"></a><span class="lineno">  939</span><span class="comment">   * @param msg</span></div>
<div class="line"><a id="l00940" name="l00940"></a><span class="lineno">  940</span><span class="comment">   *        The out-message, which may or may not store a #Native_handle.</span></div>
<div class="line"><a id="l00941" name="l00941"></a><span class="lineno">  941</span><span class="comment">   * @param originating_msg_or_null</span></div>
<div class="line"><a id="l00942" name="l00942"></a><span class="lineno">  942</span><span class="comment">   *        Pointer to the in-message to which this is responding.  If the in-message is from another</span></div>
<div class="line"><a id="l00943" name="l00943"></a><span class="lineno">  943</span><span class="comment">   *        struc::Channel, behavior is undefined.  Set to null if this message is unsolicited (not a response).</span></div>
<div class="line"><a id="l00944" name="l00944"></a><span class="lineno">  944</span><span class="comment">   * @param err_code</span></div>
<div class="line"><a id="l00945" name="l00945"></a><span class="lineno">  945</span><span class="comment">   *        See `flow::Error_code` docs for error reporting semantics.  #Error_code generated:</span></div>
<div class="line"><a id="l00946" name="l00946"></a><span class="lineno">  946</span><span class="comment">   *        See above.  Not `INVALID_ARGUMENT`, not `SENDS_FINISHED_CANNOT_SEND`.</span></div>
<div class="line"><a id="l00947" name="l00947"></a><span class="lineno">  947</span><span class="comment">   *        Also possible: serialization-failed errors (at least error::Code::S_INTERNAL_ERROR_SERIALIZE_LEAF_TOO_BIG</span></div>
<div class="line"><a id="l00948" name="l00948"></a><span class="lineno">  948</span><span class="comment">   *        unless `Struct_builder_config` is SHM-based).</span></div>
<div class="line"><a id="l00949" name="l00949"></a><span class="lineno">  949</span><span class="comment">   * @return `false` if no-op-ing due to one of the following conditions:</span></div>
<div class="line"><a id="l00950" name="l00950"></a><span class="lineno">  950</span><span class="comment">   *         invoked in logging-in phase as client; invoked in logging-in phase as server but</span></div>
<div class="line"><a id="l00951" name="l00951"></a><span class="lineno">  951</span><span class="comment">   *         `originating_msg_or_null` is null; `msg` with-handle, but #Owned_channel has no handles pipe;</span></div>
<div class="line"><a id="l00952" name="l00952"></a><span class="lineno">  952</span><span class="comment">   *         an #Error_code was previously emitted via on-error handler or send() / async_request() / sync_request();</span></div>
<div class="line"><a id="l00953" name="l00953"></a><span class="lineno">  953</span><span class="comment">   *         async_end_sending() has already been called.</span></div>
<div class="line"><a id="l00954" name="l00954"></a><span class="lineno">  954</span><span class="comment">   *         `true` otherwise (but some #Error_code may be emitted due to send failure).</span></div>
<div class="line"><a id="l00955" name="l00955"></a><span class="lineno">  955</span><span class="comment">   */</span></div>
<div class="line"><a id="l00956" name="l00956"></a><span class="lineno">  956</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae645cb58ad9ea6374970f1f32c5da448">send</a>(<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">Msg_out</a>&amp; msg, <span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a05d1cd2fc6a81a39c50a24322fb5c165">Msg_in</a>* originating_msg_or_null = 0, <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a>* err_code = 0);</div>
<div class="line"><a id="l00957" name="l00957"></a><span class="lineno">  957</span><span class="comment"></span> </div>
<div class="line"><a id="l00958" name="l00958"></a><span class="lineno">  958</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00959" name="l00959"></a><span class="lineno">  959</span><span class="comment">   * Identical to send() sends the out-message not as a *notification* but as a *request*,</span></div>
<div class="line"><a id="l00960" name="l00960"></a><span class="lineno">  960</span><span class="comment">   * registering the expectation of 1+ response(s) to it, async-invoking the provided response handler once reponse(s)</span></div>
<div class="line"><a id="l00961" name="l00961"></a><span class="lineno">  961</span><span class="comment">   * arrive(s).  `id_unless_one_off = nullptr` means up to exactly 1 response in-message shall be allowed, hence</span></div>
<div class="line"><a id="l00962" name="l00962"></a><span class="lineno">  962</span><span class="comment">   * `on_rsp_func()` shall execute at most once; at which point the expectation shall be unregistered.</span></div>
<div class="line"><a id="l00963" name="l00963"></a><span class="lineno">  963</span><span class="comment">   * `id_unless_one_off != nullptr` means responses shall be allowed (and passed to response handler) arbitrarily</span></div>
<div class="line"><a id="l00964" name="l00964"></a><span class="lineno">  964</span><span class="comment">   * many times -- until one calls undo_expect_responses() (specifically `undo_expect_responses(*id_unless_one_off)`).</span></div>
<div class="line"><a id="l00965" name="l00965"></a><span class="lineno">  965</span><span class="comment">   *</span></div>
<div class="line"><a id="l00966" name="l00966"></a><span class="lineno">  966</span><span class="comment">   * This variation on send() shall no-op (and return `false`) if one of the following is true.</span></div>
<div class="line"><a id="l00967" name="l00967"></a><span class="lineno">  967</span><span class="comment">   *   - Log-in phase, as a client, has not yet been completed, and `originating_msg_or_null` is non-null.</span></div>
<div class="line"><a id="l00968" name="l00968"></a><span class="lineno">  968</span><span class="comment">   *     Use null instead.</span></div>
<div class="line"><a id="l00969" name="l00969"></a><span class="lineno">  969</span><span class="comment">   *   - Log-in phase, as a server, has not yet been completed, and `originating_msg_or_null` is null.</span></div>
<div class="line"><a id="l00970" name="l00970"></a><span class="lineno">  970</span><span class="comment">   *     Use non-null instead.</span></div>
<div class="line"><a id="l00971" name="l00971"></a><span class="lineno">  971</span><span class="comment">   *</span></div>
<div class="line"><a id="l00972" name="l00972"></a><span class="lineno">  972</span><span class="comment">   * Further documentation of behavior shall assume this no-op condition is not the case.</span></div>
<div class="line"><a id="l00973" name="l00973"></a><span class="lineno">  973</span><span class="comment">   *</span></div>
<div class="line"><a id="l00974" name="l00974"></a><span class="lineno">  974</span><span class="comment">   * @see send() which sends a *notification* (same thing as here but *without* expecting response(s)).</span></div>
<div class="line"><a id="l00975" name="l00975"></a><span class="lineno">  975</span><span class="comment">   * @note You may use this in any phase (logged-in; or logging-in, as server or client).</span></div>
<div class="line"><a id="l00976" name="l00976"></a><span class="lineno">  976</span><span class="comment">   * @note Informally: In log-in phase, as a server, it would be unorthodox to use this method: `msg`</span></div>
<div class="line"><a id="l00977" name="l00977"></a><span class="lineno">  977</span><span class="comment">   *       by definition must be the log-in response; and it would be unusual for the log-in response to itself</span></div>
<div class="line"><a id="l00978" name="l00978"></a><span class="lineno">  978</span><span class="comment">   *       be a request for another response (or even multiple).  Nevertheless this *is* allowed; use cases are</span></div>
<div class="line"><a id="l00979" name="l00979"></a><span class="lineno">  979</span><span class="comment">   *       conceivable, and there is no reason to restrict this.  However note: As discussed elsewhere,</span></div>
<div class="line"><a id="l00980" name="l00980"></a><span class="lineno">  980</span><span class="comment">   *       logged-in phase is reached (as a server) the moment async_request() succeeds.  Any further responses are</span></div>
<div class="line"><a id="l00981" name="l00981"></a><span class="lineno">  981</span><span class="comment">   *       irrelevant to that (but could in theory be useful for some other purpose).</span></div>
<div class="line"><a id="l00982" name="l00982"></a><span class="lineno">  982</span><span class="comment">   *</span></div>
<div class="line"><a id="l00983" name="l00983"></a><span class="lineno">  983</span><span class="comment">   * All non-conflicting notes from send() apply here.</span></div>
<div class="line"><a id="l00984" name="l00984"></a><span class="lineno">  984</span><span class="comment">   *</span></div>
<div class="line"><a id="l00985" name="l00985"></a><span class="lineno">  985</span><span class="comment">   * @see async_end_sending() for properly flushing out-messages near the end of `*this` lifetime.</span></div>
<div class="line"><a id="l00986" name="l00986"></a><span class="lineno">  986</span><span class="comment">   *</span></div>
<div class="line"><a id="l00987" name="l00987"></a><span class="lineno">  987</span><span class="comment">   * @tparam On_msg_handler</span></div>
<div class="line"><a id="l00988" name="l00988"></a><span class="lineno">  988</span><span class="comment">   *         See expect_msg().</span></div>
<div class="line"><a id="l00989" name="l00989"></a><span class="lineno">  989</span><span class="comment">   * @param msg</span></div>
<div class="line"><a id="l00990" name="l00990"></a><span class="lineno">  990</span><span class="comment">   *        See send().</span></div>
<div class="line"><a id="l00991" name="l00991"></a><span class="lineno">  991</span><span class="comment">   * @param originating_msg_or_null</span></div>
<div class="line"><a id="l00992" name="l00992"></a><span class="lineno">  992</span><span class="comment">   *        Pointer to the in-message to which this is responding.  If the in-message is from another</span></div>
<div class="line"><a id="l00993" name="l00993"></a><span class="lineno">  993</span><span class="comment">   *        struc::Channel, behavior is undefined.  Set to null if this message is unsolicited (not a response).</span></div>
<div class="line"><a id="l00994" name="l00994"></a><span class="lineno">  994</span><span class="comment">   * @param id_unless_one_off</span></div>
<div class="line"><a id="l00995" name="l00995"></a><span class="lineno">  995</span><span class="comment">   *        See above.</span></div>
<div class="line"><a id="l00996" name="l00996"></a><span class="lineno">  996</span><span class="comment">   * @param on_rsp_func</span></div>
<div class="line"><a id="l00997" name="l00997"></a><span class="lineno">  997</span><span class="comment">   *        See expect_msg().</span></div>
<div class="line"><a id="l00998" name="l00998"></a><span class="lineno">  998</span><span class="comment">   *        `on_rsp_func(M)` shall be invoked in the manner explained in class doc header,</span></div>
<div class="line"><a id="l00999" name="l00999"></a><span class="lineno">  999</span><span class="comment">   *        on receipt of message M that indicates `msg` was its originating request.</span></div>
<div class="line"><a id="l01000" name="l01000"></a><span class="lineno"> 1000</span><span class="comment">   *        (On truthy `id_unless_one_off` it may be invoked more than once, until undo_expect_responses().)</span></div>
<div class="line"><a id="l01001" name="l01001"></a><span class="lineno"> 1001</span><span class="comment">   * @param err_code</span></div>
<div class="line"><a id="l01002" name="l01002"></a><span class="lineno"> 1002</span><span class="comment">   *        See send().  Note: No error is possible on account of `on_rsp_func` and `id_unless_one_off`, additions</span></div>
<div class="line"><a id="l01003" name="l01003"></a><span class="lineno"> 1003</span><span class="comment">   *        over the other overload().</span></div>
<div class="line"><a id="l01004" name="l01004"></a><span class="lineno"> 1004</span><span class="comment">   * @return `false` if no-op-ing due to one of the following conditions:</span></div>
<div class="line"><a id="l01005" name="l01005"></a><span class="lineno"> 1005</span><span class="comment">   *         invoked in logging-in phase as client but `originating_msg_or_null` is non-null; invoked in</span></div>
<div class="line"><a id="l01006" name="l01006"></a><span class="lineno"> 1006</span><span class="comment">   *         logging-in phase as server but `originating_msg_or_null` is null;</span></div>
<div class="line"><a id="l01007" name="l01007"></a><span class="lineno"> 1007</span><span class="comment">   *         `msg` with-handle, but #Owned_channel has no handles pipe;</span></div>
<div class="line"><a id="l01008" name="l01008"></a><span class="lineno"> 1008</span><span class="comment">   *         an #Error_code was previously emitted via on-error handler or send() / async_request() / sync_request();</span></div>
<div class="line"><a id="l01009" name="l01009"></a><span class="lineno"> 1009</span><span class="comment">   *         async_end_sending() has already been called.</span></div>
<div class="line"><a id="l01010" name="l01010"></a><span class="lineno"> 1010</span><span class="comment">   *         `true` otherwise (but some #Error_code may be emitted due to send failure).</span></div>
<div class="line"><a id="l01011" name="l01011"></a><span class="lineno"> 1011</span><span class="comment">   */</span></div>
<div class="line"><a id="l01012" name="l01012"></a><span class="lineno"> 1012</span>  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_msg_handler&gt;</div>
<div class="line"><a id="l01013" name="l01013"></a><span class="lineno"> 1013</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a97506bcb695f22e7ca6b480bae5b2346">async_request</a>(<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">Msg_out</a>&amp; msg, <span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a05d1cd2fc6a81a39c50a24322fb5c165">Msg_in</a>* originating_msg_or_null,</div>
<div class="line"><a id="l01014" name="l01014"></a><span class="lineno"> 1014</span>                     <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4d4995b27b7a6944fbcceee7657f6413">msg_id_out_t</a>* id_unless_one_off, On_msg_handler&amp;&amp; on_rsp_func, <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a>* err_code = 0);</div>
<div class="line"><a id="l01015" name="l01015"></a><span class="lineno"> 1015</span><span class="comment"></span> </div>
<div class="line"><a id="l01016" name="l01016"></a><span class="lineno"> 1016</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01017" name="l01017"></a><span class="lineno"> 1017</span><span class="comment">   * Equivalent to the other sync_request() overload but with no timeout; meaning it shall exit only</span></div>
<div class="line"><a id="l01018" name="l01018"></a><span class="lineno"> 1018</span><span class="comment">   * once either the expected one-off response arrives, or a pipe-hosing error occurs.</span></div>
<div class="line"><a id="l01019" name="l01019"></a><span class="lineno"> 1019</span><span class="comment">   * Formally: this is simply `return sync_request(msg, originating_msg_or_null, Fine_duration::max(), err_code)`.</span></div>
<div class="line"><a id="l01020" name="l01020"></a><span class="lineno"> 1020</span><span class="comment">   *</span></div>
<div class="line"><a id="l01021" name="l01021"></a><span class="lineno"> 1021</span><span class="comment">   * @param msg</span></div>
<div class="line"><a id="l01022" name="l01022"></a><span class="lineno"> 1022</span><span class="comment">   *        See other sync_request().</span></div>
<div class="line"><a id="l01023" name="l01023"></a><span class="lineno"> 1023</span><span class="comment">   * @param originating_msg_or_null</span></div>
<div class="line"><a id="l01024" name="l01024"></a><span class="lineno"> 1024</span><span class="comment">   *        See other sync_request().</span></div>
<div class="line"><a id="l01025" name="l01025"></a><span class="lineno"> 1025</span><span class="comment">   * @param err_code</span></div>
<div class="line"><a id="l01026" name="l01026"></a><span class="lineno"> 1026</span><span class="comment">   *        See other sync_request().</span></div>
<div class="line"><a id="l01027" name="l01027"></a><span class="lineno"> 1027</span><span class="comment">   * @return See other sync_request().</span></div>
<div class="line"><a id="l01028" name="l01028"></a><span class="lineno"> 1028</span><span class="comment">   */</span></div>
<div class="line"><a id="l01029" name="l01029"></a><span class="lineno"> 1029</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#aa41aee3c76035f43833078e625e6ef78">sync_request</a>(<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">Msg_out</a>&amp; msg, <span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a05d1cd2fc6a81a39c50a24322fb5c165">Msg_in</a>* originating_msg_or_null = 0, <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a>* err_code = 0);</div>
<div class="line"><a id="l01030" name="l01030"></a><span class="lineno"> 1030</span><span class="comment"></span> </div>
<div class="line"><a id="l01031" name="l01031"></a><span class="lineno"> 1031</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01032" name="l01032"></a><span class="lineno"> 1032</span><span class="comment">   * A blocking (subject to timeout) operation that first acts as-if async_request() was invoked</span></div>
<div class="line"><a id="l01033" name="l01033"></a><span class="lineno"> 1033</span><span class="comment">   * in one-off-request mode; then awaits the one-off response and synchronously returns that reponse</span></div>
<div class="line"><a id="l01034" name="l01034"></a><span class="lineno"> 1034</span><span class="comment">   * (or pipe-hosing error, or timeout error).</span></div>
<div class="line"><a id="l01035" name="l01035"></a><span class="lineno"> 1035</span><span class="comment">   *</span></div>
<div class="line"><a id="l01036" name="l01036"></a><span class="lineno"> 1036</span><span class="comment">   * Unlike send() and async_request(), you *may not* invoke this method directly from an in-message handler or other</span></div>
<div class="line"><a id="l01037" name="l01037"></a><span class="lineno"> 1037</span><span class="comment">   * handler.  Doing so can disrupt the timeliness of delivering async results and formally results in undefined</span></div>
<div class="line"><a id="l01038" name="l01038"></a><span class="lineno"> 1038</span><span class="comment">   * behavior.</span></div>
<div class="line"><a id="l01039" name="l01039"></a><span class="lineno"> 1039</span><span class="comment">   *</span></div>
<div class="line"><a id="l01040" name="l01040"></a><span class="lineno"> 1040</span><span class="comment">   * sync_request() shall no-op (and return null without a truthy `Error_code` emitted) if:</span></div>
<div class="line"><a id="l01041" name="l01041"></a><span class="lineno"> 1041</span><span class="comment">   *   - log-in phase has not yet been completed.</span></div>
<div class="line"><a id="l01042" name="l01042"></a><span class="lineno"> 1042</span><span class="comment">   *</span></div>
<div class="line"><a id="l01043" name="l01043"></a><span class="lineno"> 1043</span><span class="comment">   * Further documentation of behavior (except &quot;Thread safety, concurrency&quot;) shall assume this no-op condition is</span></div>
<div class="line"><a id="l01044" name="l01044"></a><span class="lineno"> 1044</span><span class="comment">   * not the case.</span></div>
<div class="line"><a id="l01045" name="l01045"></a><span class="lineno"> 1045</span><span class="comment">   *</span></div>
<div class="line"><a id="l01046" name="l01046"></a><span class="lineno"> 1046</span><span class="comment">   * ### Thread safety, concurrency ###</span></div>
<div class="line"><a id="l01047" name="l01047"></a><span class="lineno"> 1047</span><span class="comment">   * Per class doc header: yes, you can invoke `this-&gt;sync_request()` concurrently to all other `*this` methods</span></div>
<div class="line"><a id="l01048" name="l01048"></a><span class="lineno"> 1048</span><span class="comment">   * including sync_request() itself.  However beware that if you invoke 2 `sync_request()`s concurrently 1</span></div>
<div class="line"><a id="l01049" name="l01049"></a><span class="lineno"> 1049</span><span class="comment">   * will not proceed until the other finishes, even if it must block.  (By setting up handlers appropriately</span></div>
<div class="line"><a id="l01050" name="l01050"></a><span class="lineno"> 1050</span><span class="comment">   * ahead of sync_request() invocations you can ensure in local IPC that these calls will be non-blocking.)</span></div>
<div class="line"><a id="l01051" name="l01051"></a><span class="lineno"> 1051</span><span class="comment">   *</span></div>
<div class="line"><a id="l01052" name="l01052"></a><span class="lineno"> 1052</span><span class="comment">   * Furthermore, during the potentially-blocking portion of sync_request(), wherein it awaits the response or timeout,</span></div>
<div class="line"><a id="l01053" name="l01053"></a><span class="lineno"> 1053</span><span class="comment">   * other API calls shall execute non-blockingly rather than potentially-block waiting for sync_request() to return.</span></div>
<div class="line"><a id="l01054" name="l01054"></a><span class="lineno"> 1054</span><span class="comment">   * For example, a send() or async_request() will execute immediately.</span></div>
<div class="line"><a id="l01055" name="l01055"></a><span class="lineno"> 1055</span><span class="comment">   *</span></div>
<div class="line"><a id="l01056" name="l01056"></a><span class="lineno"> 1056</span><span class="comment">   * @todo Improve ipc::transport::struc::Channel::sync_request(), so that 2 such calls on the same `Channel`</span></div>
<div class="line"><a id="l01057" name="l01057"></a><span class="lineno"> 1057</span><span class="comment">   * can execute without one having to fully block the other.  Note this may be seen as a *breaking change* of sorts</span></div>
<div class="line"><a id="l01058" name="l01058"></a><span class="lineno"> 1058</span><span class="comment">   * for the purposes of release notes (even though it would presumably be seen as an improvement).</span></div>
<div class="line"><a id="l01059" name="l01059"></a><span class="lineno"> 1059</span><span class="comment">   *</span></div>
<div class="line"><a id="l01060" name="l01060"></a><span class="lineno"> 1060</span><span class="comment">   * ### Send mechanics  ###</span></div>
<div class="line"><a id="l01061" name="l01061"></a><span class="lineno"> 1061</span><span class="comment">   * As the first step this method invokes essentially async_request().  Hence the following notes apply as they do</span></div>
<div class="line"><a id="l01062" name="l01062"></a><span class="lineno"> 1062</span><span class="comment">   * for async_request():</span></div>
<div class="line"><a id="l01063" name="l01063"></a><span class="lineno"> 1063</span><span class="comment">   * Long story short, it reports errors similarly to the core Blob_sender::send_blob() or</span></div>
<div class="line"><a id="l01064" name="l01064"></a><span class="lineno"> 1064</span><span class="comment">   * Native_handle_sender::send_native_handle() with the following differences:</span></div>
<div class="line"><a id="l01065" name="l01065"></a><span class="lineno"> 1065</span><span class="comment">   *   - If `msg` contains a #Native_handle, but #Owned_channel has no native-handles pipe: no-op, return null</span></div>
<div class="line"><a id="l01066" name="l01066"></a><span class="lineno"> 1066</span><span class="comment">   *     with falsy `Error_code`.</span></div>
<div class="line"><a id="l01067" name="l01067"></a><span class="lineno"> 1067</span><span class="comment">   *   - If called after async_end_sending(): no-op, return null with falsy `Error_code`.</span></div>
<div class="line"><a id="l01068" name="l01068"></a><span class="lineno"> 1068</span><span class="comment">   *   - If called after a background receive or preceding send() / async_request() / sync_request()</span></div>
<div class="line"><a id="l01069" name="l01069"></a><span class="lineno"> 1069</span><span class="comment">   *     emitted error: no-op, return null with falsy `Error_code`.</span></div>
<div class="line"><a id="l01070" name="l01070"></a><span class="lineno"> 1070</span><span class="comment">   *   - Otherwise it&#39;ll attempt the core `send_*()`.</span></div>
<div class="line"><a id="l01071" name="l01071"></a><span class="lineno"> 1071</span><span class="comment">   *     - If that yields a (pipe-hosing) error, then: return null with truthy `Error_code` emitted.</span></div>
<div class="line"><a id="l01072" name="l01072"></a><span class="lineno"> 1072</span><span class="comment">   *       - And `*this` shall be considered hosed for any subsequent transmission.</span></div>
<div class="line"><a id="l01073" name="l01073"></a><span class="lineno"> 1073</span><span class="comment">   *     - Otherwise the method moves on to the wait phase.</span></div>
<div class="line"><a id="l01074" name="l01074"></a><span class="lineno"> 1074</span><span class="comment">   *</span></div>
<div class="line"><a id="l01075" name="l01075"></a><span class="lineno"> 1075</span><span class="comment">   * The result of the wait phase shall be one of:</span></div>
<div class="line"><a id="l01076" name="l01076"></a><span class="lineno"> 1076</span><span class="comment">   *   - non-null response returned, no truthy `Error_code` emitted (success);</span></div>
<div class="line"><a id="l01077" name="l01077"></a><span class="lineno"> 1077</span><span class="comment">   *   - null response returned, truthy `Error_code` that is not transport::error::Code::S_TIMEOUT (pipe hosed during</span></div>
<div class="line"><a id="l01078" name="l01078"></a><span class="lineno"> 1078</span><span class="comment">   *     wait);</span></div>
<div class="line"><a id="l01079" name="l01079"></a><span class="lineno"> 1079</span><span class="comment">   *   - null response returned, `Error_code == S_TIMEOUT` (pipe is fine, but the wait timed out).</span></div>
<div class="line"><a id="l01080" name="l01080"></a><span class="lineno"> 1080</span><span class="comment">   *</span></div>
<div class="line"><a id="l01081" name="l01081"></a><span class="lineno"> 1081</span><span class="comment">   * ### Late-response semantics ###</span></div>
<div class="line"><a id="l01082" name="l01082"></a><span class="lineno"> 1082</span><span class="comment">   * If the response, or pipe-hosing error, occurs during this method&#39;s wait, then hopefully everything is clear.</span></div>
<div class="line"><a id="l01083" name="l01083"></a><span class="lineno"> 1083</span><span class="comment">   * Now suppose it does time out and hence emits `Error_code` transport::error::Code::S_TIMEOUT.</span></div>
<div class="line"><a id="l01084" name="l01084"></a><span class="lineno"> 1084</span><span class="comment">   * In the background `*this` continues to await the one-off response.  (Moreover it is not possible to</span></div>
<div class="line"><a id="l01085" name="l01085"></a><span class="lineno"> 1085</span><span class="comment">   * &quot;un-expect&quot; it or expect a response some other way; as response expectation can only be specified</span></div>
<div class="line"><a id="l01086" name="l01086"></a><span class="lineno"> 1086</span><span class="comment">   * at async_request() or sync_request() time, and you&#39;ve already done the latter for that out-message, and a one-off</span></div>
<div class="line"><a id="l01087" name="l01087"></a><span class="lineno"> 1087</span><span class="comment">   * request expectation by convention cannot be undone as of this writing.)</span></div>
<div class="line"><a id="l01088" name="l01088"></a><span class="lineno"> 1088</span><span class="comment">   *</span></div>
<div class="line"><a id="l01089" name="l01089"></a><span class="lineno"> 1089</span><span class="comment">   * If the response (after timeout) never arrives, there&#39;s nothing further to discuss.</span></div>
<div class="line"><a id="l01090" name="l01090"></a><span class="lineno"> 1090</span><span class="comment">   *</span></div>
<div class="line"><a id="l01091" name="l01091"></a><span class="lineno"> 1091</span><span class="comment">   * Now suppose it does arrive at some point (after the timeout).</span></div>
<div class="line"><a id="l01092" name="l01092"></a><span class="lineno"> 1092</span><span class="comment">   * It shall be handled as-if an unexpected response was received (albeit with slightly different args as noted</span></div>
<div class="line"><a id="l01093" name="l01093"></a><span class="lineno"> 1093</span><span class="comment">   * just below).  Namely:</span></div>
<div class="line"><a id="l01094" name="l01094"></a><span class="lineno"> 1094</span><span class="comment">   *   - If set_unexpected_response_handler() is in effect, it shall be invoked (with `expected_but_timed_out` set).</span></div>
<div class="line"><a id="l01095" name="l01095"></a><span class="lineno"> 1095</span><span class="comment">   *   - The opposing peer is informed of this event, and if on that side set_remote_unexpected_response_handler()</span></div>
<div class="line"><a id="l01096" name="l01096"></a><span class="lineno"> 1096</span><span class="comment">   *     is in effect, the opposing-side user shall be informed via that handler (again</span></div>
<div class="line"><a id="l01097" name="l01097"></a><span class="lineno"> 1097</span><span class="comment">   *     with a flag indicating expected-but-timed-out).</span></div>
<div class="line"><a id="l01098" name="l01098"></a><span class="lineno"> 1098</span><span class="comment">   *</span></div>
<div class="line"><a id="l01099" name="l01099"></a><span class="lineno"> 1099</span><span class="comment">   * @param msg</span></div>
<div class="line"><a id="l01100" name="l01100"></a><span class="lineno"> 1100</span><span class="comment">   *        See async_request().</span></div>
<div class="line"><a id="l01101" name="l01101"></a><span class="lineno"> 1101</span><span class="comment">   * @param originating_msg_or_null</span></div>
<div class="line"><a id="l01102" name="l01102"></a><span class="lineno"> 1102</span><span class="comment">   *        See async_request().</span></div>
<div class="line"><a id="l01103" name="l01103"></a><span class="lineno"> 1103</span><span class="comment">   * @param timeout</span></div>
<div class="line"><a id="l01104" name="l01104"></a><span class="lineno"> 1104</span><span class="comment">   *        If no appropriate response to `msg` occurs, nor does a pipe-hosing error, before this time elapses</span></div>
<div class="line"><a id="l01105" name="l01105"></a><span class="lineno"> 1105</span><span class="comment">   *        sync_request() shall emit transport::error::Code::S_TIMEOUT.  Note that the latter does *not* indicate</span></div>
<div class="line"><a id="l01106" name="l01106"></a><span class="lineno"> 1106</span><span class="comment">   *        the pipe has been hosed.  To disable timeout you *must* use the special value</span></div>
<div class="line"><a id="l01107" name="l01107"></a><span class="lineno"> 1107</span><span class="comment">   *        `util::Fine_duration::max()`.  (Rationale: Internally, a certain boost.thread API may use</span></div>
<div class="line"><a id="l01108" name="l01108"></a><span class="lineno"> 1108</span><span class="comment">   *        `pthread_cond_timedwait()` internally; this function in at least some Linuxes barfs on very high values</span></div>
<div class="line"><a id="l01109" name="l01109"></a><span class="lineno"> 1109</span><span class="comment">   *        of `Fine_duration`, as they translate into negative absolute `timespec` components.  Therefore we</span></div>
<div class="line"><a id="l01110" name="l01110"></a><span class="lineno"> 1110</span><span class="comment">   *        detect the specific desire to have unlimited timeout and in that case use un-timed wait.)</span></div>
<div class="line"><a id="l01111" name="l01111"></a><span class="lineno"> 1111</span><span class="comment">   * @param err_code</span></div>
<div class="line"><a id="l01112" name="l01112"></a><span class="lineno"> 1112</span><span class="comment">   *        See `flow::Error_code` docs for error reporting semantics.  #Error_code generated: See</span></div>
<div class="line"><a id="l01113" name="l01113"></a><span class="lineno"> 1113</span><span class="comment">   *        async_request().  If the initial non-blocking send succeeds then other #Error_code possibilities</span></div>
<div class="line"><a id="l01114" name="l01114"></a><span class="lineno"> 1114</span><span class="comment">   *        include: Any pipe-hosing error that might be otherwise emitted outside a `sync_*()` due to</span></div>
<div class="line"><a id="l01115" name="l01115"></a><span class="lineno"> 1115</span><span class="comment">   *        in-traffic; and transport::error::Code::S_TIMEOUT.  Note that the latter does *not* indicate the pipe has</span></div>
<div class="line"><a id="l01116" name="l01116"></a><span class="lineno"> 1116</span><span class="comment">   *        been hosed.</span></div>
<div class="line"><a id="l01117" name="l01117"></a><span class="lineno"> 1117</span><span class="comment">   * @return Non-null response message on success within timeout; otherwise null.</span></div>
<div class="line"><a id="l01118" name="l01118"></a><span class="lineno"> 1118</span><span class="comment">   *         If null, emitted `S_TIMEOUT` indicates non-fatal timeout; emitted other truthy `Error_code` indicates</span></div>
<div class="line"><a id="l01119" name="l01119"></a><span class="lineno"> 1119</span><span class="comment">   *         either the non-blocking send emitted pipe-hosing error, or during the wait the pipe got hosed.</span></div>
<div class="line"><a id="l01120" name="l01120"></a><span class="lineno"> 1120</span><span class="comment">   *         If null, but no `Error_code` is emitted, then the method was a non-blocking no-op for one</span></div>
<div class="line"><a id="l01121" name="l01121"></a><span class="lineno"> 1121</span><span class="comment">   *         of the reasons listed above:</span></div>
<div class="line"><a id="l01122" name="l01122"></a><span class="lineno"> 1122</span><span class="comment">   *         invoked in logging-in phase; `msg` with-handle, but #Owned_channel has no handles pipe;</span></div>
<div class="line"><a id="l01123" name="l01123"></a><span class="lineno"> 1123</span><span class="comment">   *         an #Error_code was previously emitted via on-error handler or send() / async_request() / sync_request();</span></div>
<div class="line"><a id="l01124" name="l01124"></a><span class="lineno"> 1124</span><span class="comment">   *         async_end_sending() has already been called.</span></div>
<div class="line"><a id="l01125" name="l01125"></a><span class="lineno"> 1125</span><span class="comment">   */</span></div>
<div class="line"><a id="l01126" name="l01126"></a><span class="lineno"> 1126</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#aa41aee3c76035f43833078e625e6ef78">sync_request</a>(<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">Msg_out</a>&amp; msg, <span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a05d1cd2fc6a81a39c50a24322fb5c165">Msg_in</a>* originating_msg_or_null,</div>
<div class="line"><a id="l01127" name="l01127"></a><span class="lineno"> 1127</span>                          <a class="code hl_typedef" href="namespaceipc_1_1util.html#ac66141280c3b7295a86b65209f31cc58">util::Fine_duration</a> timeout, <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a>* err_code);</div>
<div class="line"><a id="l01128" name="l01128"></a><span class="lineno"> 1128</span><span class="comment"></span> </div>
<div class="line"><a id="l01129" name="l01129"></a><span class="lineno"> 1129</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01130" name="l01130"></a><span class="lineno"> 1130</span><span class="comment">   * Unregisters the expectation earlier-registered with the `id_unless_one_off != nullptr` form of</span></div>
<div class="line"><a id="l01131" name="l01131"></a><span class="lineno"> 1131</span><span class="comment">   * async_request().  No-op and return `false` if response to `originating_msg_id_or_none` is not being</span></div>
<div class="line"><a id="l01132" name="l01132"></a><span class="lineno"> 1132</span><span class="comment">   * expected, if log-in phase is not yet completed, or if a prior error has hosed the owned transport::Channel.</span></div>
<div class="line"><a id="l01133" name="l01133"></a><span class="lineno"> 1133</span><span class="comment">   *</span></div>
<div class="line"><a id="l01134" name="l01134"></a><span class="lineno"> 1134</span><span class="comment">   * @note It is not possible to unregister an expected response without first `async_request()`ing the thing to which</span></div>
<div class="line"><a id="l01135" name="l01135"></a><span class="lineno"> 1135</span><span class="comment">   *       such a response would pertain.  If you don&#39;t want responses to a thing that&#39;s not yet sent, then</span></div>
<div class="line"><a id="l01136" name="l01136"></a><span class="lineno"> 1136</span><span class="comment">   *       don&#39;t send it.</span></div>
<div class="line"><a id="l01137" name="l01137"></a><span class="lineno"> 1137</span><span class="comment">   *</span></div>
<div class="line"><a id="l01138" name="l01138"></a><span class="lineno"> 1138</span><span class="comment">   * @param originating_msg_id</span></div>
<div class="line"><a id="l01139" name="l01139"></a><span class="lineno"> 1139</span><span class="comment">   *        The value `x` from an earlier successful `async_request(M, ..., &amp;x, F)` call, where `M` is the request</span></div>
<div class="line"><a id="l01140" name="l01140"></a><span class="lineno"> 1140</span><span class="comment">   *        out-message, F is the response handler.</span></div>
<div class="line"><a id="l01141" name="l01141"></a><span class="lineno"> 1141</span><span class="comment">   * @return `true` on success; `false` due to one of the above conditions.</span></div>
<div class="line"><a id="l01142" name="l01142"></a><span class="lineno"> 1142</span><span class="comment">   */</span></div>
<div class="line"><a id="l01143" name="l01143"></a><span class="lineno"> 1143</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a34780bd3507a571cb719ce1d59e5d56f">undo_expect_responses</a>(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4d4995b27b7a6944fbcceee7657f6413">msg_id_out_t</a> originating_msg_id);</div>
<div class="line"><a id="l01144" name="l01144"></a><span class="lineno"> 1144</span><span class="comment"></span> </div>
<div class="line"><a id="l01145" name="l01145"></a><span class="lineno"> 1145</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01146" name="l01146"></a><span class="lineno"> 1146</span><span class="comment">   * Registers the handler to invoke when a response in-message arrives, but no response-expectation</span></div>
<div class="line"><a id="l01147" name="l01147"></a><span class="lineno"> 1147</span><span class="comment">   * has been registered (via async_request()), or the one-off request had been previously satisfied</span></div>
<div class="line"><a id="l01148" name="l01148"></a><span class="lineno"> 1148</span><span class="comment">   * with another response, or undo_expect_responses() has been issued for an open-ended request,</span></div>
<div class="line"><a id="l01149" name="l01149"></a><span class="lineno"> 1149</span><span class="comment">   * or the response is to sync_request() that has timed out.  No-op and return `false` if a handler is already</span></div>
<div class="line"><a id="l01150" name="l01150"></a><span class="lineno"> 1150</span><span class="comment">   * registered.</span></div>
<div class="line"><a id="l01151" name="l01151"></a><span class="lineno"> 1151</span><span class="comment">   *</span></div>
<div class="line"><a id="l01152" name="l01152"></a><span class="lineno"> 1152</span><span class="comment">   * Note that, regardless of whether this handler is registered: If an unsolicited response does arrive,</span></div>
<div class="line"><a id="l01153" name="l01153"></a><span class="lineno"> 1153</span><span class="comment">   * the opposing (offending) peer shall be informed of this.  See set_remote_unexpected_response_handler() for</span></div>
<div class="line"><a id="l01154" name="l01154"></a><span class="lineno"> 1154</span><span class="comment">   * what that is like from their point of view.</span></div>
<div class="line"><a id="l01155" name="l01155"></a><span class="lineno"> 1155</span><span class="comment">   *</span></div>
<div class="line"><a id="l01156" name="l01156"></a><span class="lineno"> 1156</span><span class="comment">   * Lastly note that, while this and unset_unexpected_response_handler() can be invoked during logging-in phase,</span></div>
<div class="line"><a id="l01157" name="l01157"></a><span class="lineno"> 1157</span><span class="comment">   * `on_func()` won&#39;t fire until the logged-in phase.  To be clear: Nothing is &quot;deferred&quot;; that condition simply</span></div>
<div class="line"><a id="l01158" name="l01158"></a><span class="lineno"> 1158</span><span class="comment">   * cannot occur until the logged-in phase.  An unexpected response during the highly rigid logging-in phase</span></div>
<div class="line"><a id="l01159" name="l01159"></a><span class="lineno"> 1159</span><span class="comment">   * is treated as a channel-hosing (fatal) condition.</span></div>
<div class="line"><a id="l01160" name="l01160"></a><span class="lineno"> 1160</span><span class="comment">   *</span></div>
<div class="line"><a id="l01161" name="l01161"></a><span class="lineno"> 1161</span><span class="comment">   * @tparam On_unexpected_response_handler</span></div>
<div class="line"><a id="l01162" name="l01162"></a><span class="lineno"> 1162</span><span class="comment">   *         Functor type with signature compatible with `void F(Msg_in_ptr&amp;&amp;)`.</span></div>
<div class="line"><a id="l01163" name="l01163"></a><span class="lineno"> 1163</span><span class="comment">   * @param on_func</span></div>
<div class="line"><a id="l01164" name="l01164"></a><span class="lineno"> 1164</span><span class="comment">   *        `on_func(M, B)` shall be fired, where `M` is the offending in-message;</span></div>
<div class="line"><a id="l01165" name="l01165"></a><span class="lineno"> 1165</span><span class="comment">   *        `B` is `true` if this is a response to a timed-out sync_request(), `false` otherwise.</span></div>
<div class="line"><a id="l01166" name="l01166"></a><span class="lineno"> 1166</span><span class="comment">   * @return `true` on success; `false` due to one of the above conditions.</span></div>
<div class="line"><a id="l01167" name="l01167"></a><span class="lineno"> 1167</span><span class="comment">   */</span></div>
<div class="line"><a id="l01168" name="l01168"></a><span class="lineno"> 1168</span>  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_unexpected_response_handler&gt;</div>
<div class="line"><a id="l01169" name="l01169"></a><span class="lineno"> 1169</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#ab7cd0bed6392cb155f9ee21071c5226b">set_unexpected_response_handler</a>(On_unexpected_response_handler&amp;&amp; on_func);</div>
<div class="line"><a id="l01170" name="l01170"></a><span class="lineno"> 1170</span><span class="comment"></span> </div>
<div class="line"><a id="l01171" name="l01171"></a><span class="lineno"> 1171</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01172" name="l01172"></a><span class="lineno"> 1172</span><span class="comment">   * Undoes set_unexpected_response_handler().  No-op and return `false` if no handler is registered anyway.</span></div>
<div class="line"><a id="l01173" name="l01173"></a><span class="lineno"> 1173</span><span class="comment">   *</span></div>
<div class="line"><a id="l01174" name="l01174"></a><span class="lineno"> 1174</span><span class="comment">   * @return See above.</span></div>
<div class="line"><a id="l01175" name="l01175"></a><span class="lineno"> 1175</span><span class="comment">   */</span></div>
<div class="line"><a id="l01176" name="l01176"></a><span class="lineno"> 1176</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#ad3070c369762b2f5e85555155f65bdaa">unset_unexpected_response_handler</a>();</div>
<div class="line"><a id="l01177" name="l01177"></a><span class="lineno"> 1177</span><span class="comment"></span> </div>
<div class="line"><a id="l01178" name="l01178"></a><span class="lineno"> 1178</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01179" name="l01179"></a><span class="lineno"> 1179</span><span class="comment">   * Registers the handler to invoke when the *remote* peer encounters the condition that would fire</span></div>
<div class="line"><a id="l01180" name="l01180"></a><span class="lineno"> 1180</span><span class="comment">   * the *remote* set_unexpected_response_handler() handler (regardless of whether one is indeed remotely</span></div>
<div class="line"><a id="l01181" name="l01181"></a><span class="lineno"> 1181</span><span class="comment">   * registered), causing that peer to inform `*this` of that event in the background.</span></div>
<div class="line"><a id="l01182" name="l01182"></a><span class="lineno"> 1182</span><span class="comment">   * No-op and return `false` if a handler is already registered.</span></div>
<div class="line"><a id="l01183" name="l01183"></a><span class="lineno"> 1183</span><span class="comment">   *</span></div>
<div class="line"><a id="l01184" name="l01184"></a><span class="lineno"> 1184</span><span class="comment">   * Note that, while this and unset_remote_unexpected_response_handler() can be invoked during logging-in phase,</span></div>
<div class="line"><a id="l01185" name="l01185"></a><span class="lineno"> 1185</span><span class="comment">   * `on_func()` won&#39;t fire until the logged-in phase.  To be clear: Nothing is &quot;deferred&quot;; that condition simply</span></div>
<div class="line"><a id="l01186" name="l01186"></a><span class="lineno"> 1186</span><span class="comment">   * cannot occur until the logged-in phase.  An unexpected response during the highly rigid logging-in phase</span></div>
<div class="line"><a id="l01187" name="l01187"></a><span class="lineno"> 1187</span><span class="comment">   * is treated as a channel-hosing (fatal) condition.</span></div>
<div class="line"><a id="l01188" name="l01188"></a><span class="lineno"> 1188</span><span class="comment">   *</span></div>
<div class="line"><a id="l01189" name="l01189"></a><span class="lineno"> 1189</span><span class="comment">   * @tparam On_remote_unexpected_response_handler</span></div>
<div class="line"><a id="l01190" name="l01190"></a><span class="lineno"> 1190</span><span class="comment">   *         Functor type with signature compatible with `void F(msg_id_out_t, std::string&amp;&amp;)`.</span></div>
<div class="line"><a id="l01191" name="l01191"></a><span class="lineno"> 1191</span><span class="comment">   * @param on_func</span></div>
<div class="line"><a id="l01192" name="l01192"></a><span class="lineno"> 1192</span><span class="comment">   *        `on_func(M, B, S)` shall be fired, where `M` is the offending out-message&#39;s #msg_id_out_t (for</span></div>
<div class="line"><a id="l01193" name="l01193"></a><span class="lineno"> 1193</span><span class="comment">   *        logging/reporting only); `S` a (movable) `string` containing brief abitrary info suitable for logging</span></div>
<div class="line"><a id="l01194" name="l01194"></a><span class="lineno"> 1194</span><span class="comment">   *        about the message; and `B` is `true` if this is a response to a timed-out sync_request() on the opposing</span></div>
<div class="line"><a id="l01195" name="l01195"></a><span class="lineno"> 1195</span><span class="comment">   *        side, `false` otherwise.</span></div>
<div class="line"><a id="l01196" name="l01196"></a><span class="lineno"> 1196</span><span class="comment">   * @return `true` on success; `false` due to one of the above conditions.</span></div>
<div class="line"><a id="l01197" name="l01197"></a><span class="lineno"> 1197</span><span class="comment">   */</span></div>
<div class="line"><a id="l01198" name="l01198"></a><span class="lineno"> 1198</span>  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_remote_unexpected_response_handler&gt;</div>
<div class="line"><a id="l01199" name="l01199"></a><span class="lineno"> 1199</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a9ec7ff431b51fec8aacacccb23a2d4e3">set_remote_unexpected_response_handler</a>(On_remote_unexpected_response_handler&amp;&amp; on_func);</div>
<div class="line"><a id="l01200" name="l01200"></a><span class="lineno"> 1200</span><span class="comment"></span> </div>
<div class="line"><a id="l01201" name="l01201"></a><span class="lineno"> 1201</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01202" name="l01202"></a><span class="lineno"> 1202</span><span class="comment">   * Undoes set_remote_unexpected_response_handler().  No-op and return `false` if no handler is registered anyway.</span></div>
<div class="line"><a id="l01203" name="l01203"></a><span class="lineno"> 1203</span><span class="comment">   *</span></div>
<div class="line"><a id="l01204" name="l01204"></a><span class="lineno"> 1204</span><span class="comment">   * @return See above.</span></div>
<div class="line"><a id="l01205" name="l01205"></a><span class="lineno"> 1205</span><span class="comment">   */</span></div>
<div class="line"><a id="l01206" name="l01206"></a><span class="lineno"> 1206</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a1d5415ad72e5758f15fd49d2faabb3e0">unset_remote_unexpected_response_handler</a>();</div>
<div class="line"><a id="l01207" name="l01207"></a><span class="lineno"> 1207</span><span class="comment"></span> </div>
<div class="line"><a id="l01208" name="l01208"></a><span class="lineno"> 1208</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01209" name="l01209"></a><span class="lineno"> 1209</span><span class="comment">   * Operating at the unstructured layer, executes a graceful-close send by forwarding to the async</span></div>
<div class="line"><a id="l01210" name="l01210"></a><span class="lineno"> 1210</span><span class="comment">   * transport::Channel::async_end_sending() on the owned #Owned_channel.  Reminder: Assuming not called</span></div>
<div class="line"><a id="l01211" name="l01211"></a><span class="lineno"> 1211</span><span class="comment">   * after async_end_sending() again: it queues a graceful-close after any other messages sent previously;</span></div>
<div class="line"><a id="l01212" name="l01212"></a><span class="lineno"> 1212</span><span class="comment">   * and executes `on_done_func(E)` once that graceful-close is actually sent into the low-level transport</span></div>
<div class="line"><a id="l01213" name="l01213"></a><span class="lineno"> 1213</span><span class="comment">   * (then `E` is falsy), or a transport error is encountered at any point, including in the past (then `E`</span></div>
<div class="line"><a id="l01214" name="l01214"></a><span class="lineno"> 1214</span><span class="comment">   * is truthy).  Because the owned channel&#39;s lifetime is equal to that of `*this`, if `on_done_func()` has</span></div>
<div class="line"><a id="l01215" name="l01215"></a><span class="lineno"> 1215</span><span class="comment">   * not executed when `*this` dtor runs, it will be executed at that time with the usual</span></div>
<div class="line"><a id="l01216" name="l01216"></a><span class="lineno"> 1216</span><span class="comment">   * transport::error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER.</span></div>
<div class="line"><a id="l01217" name="l01217"></a><span class="lineno"> 1217</span><span class="comment">   *</span></div>
<div class="line"><a id="l01218" name="l01218"></a><span class="lineno"> 1218</span><span class="comment">   * `on_done_func()` shall, as usual, execute from an unspecified thread that is not among the user calling thread(s);</span></div>
<div class="line"><a id="l01219" name="l01219"></a><span class="lineno"> 1219</span><span class="comment">   * and it shall not execute concurrently to any other handler invoked by `*this`.</span></div>
<div class="line"><a id="l01220" name="l01220"></a><span class="lineno"> 1220</span><span class="comment">   *</span></div>
<div class="line"><a id="l01221" name="l01221"></a><span class="lineno"> 1221</span><span class="comment">   * Formally -- that is all it does, period.  Informally it is important to understand the relationship between</span></div>
<div class="line"><a id="l01222" name="l01222"></a><span class="lineno"> 1222</span><span class="comment">   * this call and the rest of the API which operates at the structured layer, particularly insofar as it relates</span></div>
<div class="line"><a id="l01223" name="l01223"></a><span class="lineno"> 1223</span><span class="comment">   * to the error semantics on that layer.  (Please read the class doc header first.)</span></div>
<div class="line"><a id="l01224" name="l01224"></a><span class="lineno"> 1224</span><span class="comment">   *</span></div>
<div class="line"><a id="l01225" name="l01225"></a><span class="lineno"> 1225</span><span class="comment">   * ### Why and when to use this ###</span></div>
<div class="line"><a id="l01226" name="l01226"></a><span class="lineno"> 1226</span><span class="comment">   * The short answer as to when and how to use it: While optional, the best practice is: If you are done using</span></div>
<div class="line"><a id="l01227" name="l01227"></a><span class="lineno"> 1227</span><span class="comment">   * the channel (for any reason, whether due to error -- as reported via the error handler -- but especially</span></div>
<div class="line"><a id="l01228" name="l01228"></a><span class="lineno"> 1228</span><span class="comment">   * *without* any error), you should call `async_end_sending(F)`, asynchronously wait for `F()` to execute, and in</span></div>
<div class="line"><a id="l01229" name="l01229"></a><span class="lineno"> 1229</span><span class="comment">   * or after `F()` destroy `*this` to free resources.</span></div>
<div class="line"><a id="l01230" name="l01230"></a><span class="lineno"> 1230</span><span class="comment">   *</span></div>
<div class="line"><a id="l01231" name="l01231"></a><span class="lineno"> 1231</span><span class="comment">   * The long answer which hopefully explains the short answer is as follows.  It&#39;s long, but the short answer is</span></div>
<div class="line"><a id="l01232" name="l01232"></a><span class="lineno"> 1232</span><span class="comment">   * sufficient arguably.  So read if desired.</span></div>
<div class="line"><a id="l01233" name="l01233"></a><span class="lineno"> 1233</span><span class="comment">   *</span></div>
<div class="line"><a id="l01234" name="l01234"></a><span class="lineno"> 1234</span><span class="comment">   * Let us first consider the case where no `*this` error has occurred so far, meaning the `start()`-passed error</span></div>
<div class="line"><a id="l01235" name="l01235"></a><span class="lineno"> 1235</span><span class="comment">   * handler has not been invoked, and you no longer need the channel.  The immediate thought might be, simply,</span></div>
<div class="line"><a id="l01236" name="l01236"></a><span class="lineno"> 1236</span><span class="comment">   * this means a graceful-close is in order as a matter of decent behavior, which is fair enough; although it</span></div>
<div class="line"><a id="l01237" name="l01237"></a><span class="lineno"> 1237</span><span class="comment">   * would not be wrong to implement your own application-layer message exchange for this (by adding these into</span></div>
<div class="line"><a id="l01238" name="l01238"></a><span class="lineno"> 1238</span><span class="comment">   * your #Msg_body capnp schema and sending it like any other message).  However that is *not*, I (ygoldfel)</span></div>
<div class="line"><a id="l01239" name="l01239"></a><span class="lineno"> 1239</span><span class="comment">   * contend, the main reason `async_end_sending(F)` is a good idea in this context.  That real reason: send() (et al),</span></div>
<div class="line"><a id="l01240" name="l01240"></a><span class="lineno"> 1240</span><span class="comment">   * externally, behaves as-if it is both synchronous and non-blocking yet cannot yield a would-block condition.</span></div>
<div class="line"><a id="l01241" name="l01241"></a><span class="lineno"> 1241</span><span class="comment">   * However, per Native_handle_sender and Blob_sender concept model docs, `send*()` actually may (though this should be</span></div>
<div class="line"><a id="l01242" name="l01242"></a><span class="lineno"> 1242</span><span class="comment">   * rare in practice) be internally asynchronous, in that it may encounter a would-block low-level transport</span></div>
<div class="line"><a id="l01243" name="l01243"></a><span class="lineno"> 1243</span><span class="comment">   * condition (e.g., MQ full, or local-stream-socket would-block), save a copy of the payload, and only succeed in</span></div>
<div class="line"><a id="l01244" name="l01244"></a><span class="lineno"> 1244</span><span class="comment">   * passing it to the out-wire later.  `async_end_sending(F)` can and should be viewed as the async *out-flush*: it</span></div>
<div class="line"><a id="l01245" name="l01245"></a><span class="lineno"> 1245</span><span class="comment">   * ensures all the queued sends have truly succeeded -- or a transport error triggered -- and only *then* executes</span></div>
<div class="line"><a id="l01246" name="l01246"></a><span class="lineno"> 1246</span><span class="comment">   * `F()` asynchronously.  Hence by waiting until `F()` before destroying `*this` you will have ensured that</span></div>
<div class="line"><a id="l01247" name="l01247"></a><span class="lineno"> 1247</span><span class="comment">   * all those care-free synchronous non-blocking sends have truly gone out; therefore `*this` can be destroyed</span></div>
<div class="line"><a id="l01248" name="l01248"></a><span class="lineno"> 1248</span><span class="comment">   * without accidentally cutting off the end of the conversation.</span></div>
<div class="line"><a id="l01249" name="l01249"></a><span class="lineno"> 1249</span><span class="comment">   *</span></div>
<div class="line"><a id="l01250" name="l01250"></a><span class="lineno"> 1250</span><span class="comment">   * Next let&#39;s talk about the error cases.  There are roughly 2 as of this writing.  One, a &quot;soft&quot; non-channel-hosing</span></div>
<div class="line"><a id="l01251" name="l01251"></a><span class="lineno"> 1251</span><span class="comment">   * situation can occur, namely information about a local or remote application-protocol error might trigger</span></div>
<div class="line"><a id="l01252" name="l01252"></a><span class="lineno"> 1252</span><span class="comment">   * a handler like those set by set_unexpected_response_handler() and set_remote_unexpected_response_handler().</span></div>
<div class="line"><a id="l01253" name="l01253"></a><span class="lineno"> 1253</span><span class="comment">   * While this may well indicate a serious problem to the user, `*this` does not consider it that way.  It is up</span></div>
<div class="line"><a id="l01254" name="l01254"></a><span class="lineno"> 1254</span><span class="comment">   * to the user to decide what to do when such a &quot;soft&quot; handler executes.  They could do nothing: conceivably they</span></div>
<div class="line"><a id="l01255" name="l01255"></a><span class="lineno"> 1255</span><span class="comment">   * coded in a loose way and consider this not an issue.  Or they could consider this worth ending the conversation.</span></div>
<div class="line"><a id="l01256" name="l01256"></a><span class="lineno"> 1256</span><span class="comment">   * In that case, the situation is not *too* different from the non-error case discussed above.  Want to end `*this`?</span></div>
<div class="line"><a id="l01257" name="l01257"></a><span class="lineno"> 1257</span><span class="comment">   * Flush any sends via `async_end_sending(F)`, then after `F()` destroy `*this`.  At least this features less</span></div>
<div class="line"><a id="l01258" name="l01258"></a><span class="lineno"> 1258</span><span class="comment">   * entropy and is better, or at least not worse, than abruptly destroying the transport::Channel peer (and possibly</span></div>
<div class="line"><a id="l01259" name="l01259"></a><span class="lineno"> 1259</span><span class="comment">   * whole channel).</span></div>
<div class="line"><a id="l01260" name="l01260"></a><span class="lineno"> 1260</span><span class="comment">   *</span></div>
<div class="line"><a id="l01261" name="l01261"></a><span class="lineno"> 1261</span><span class="comment">   * Lastly: Two, an actual fatal error may occur.  This is where there is some subtlety, due to the subtle difference</span></div>
<div class="line"><a id="l01262" name="l01262"></a><span class="lineno"> 1262</span><span class="comment">   * between the unstructured layer (#Owned_channel operation) and structured layer (the protocol in struc::Channel</span></div>
<div class="line"><a id="l01263" name="l01263"></a><span class="lineno"> 1263</span><span class="comment">   * on top of that).  Suppose a channel-hosing error occurs: the `start()`-passed error handler *has* been invoked; by</span></div>
<div class="line"><a id="l01264" name="l01264"></a><span class="lineno"> 1264</span><span class="comment">   * definition this means `*this` can transmit no more *structured* messages in either direction; and in fact all</span></div>
<div class="line"><a id="l01265" name="l01265"></a><span class="lineno"> 1265</span><span class="comment">   * further APIs, with the exception of async_end_sending(), will return `false` (or similar) and no-op.  However:</span></div>
<div class="line"><a id="l01266" name="l01266"></a><span class="lineno"> 1266</span><span class="comment">   * a channel-hosing error is (this is the subtlety!) one of 2 rough types.</span></div>
<div class="line"><a id="l01267" name="l01267"></a><span class="lineno"> 1267</span><span class="comment">   *   -# It might be an unstructured-layer error: the #Owned_channel was trying to send or receive some blob or handle,</span></div>
<div class="line"><a id="l01268" name="l01268"></a><span class="lineno"> 1268</span><span class="comment">   *      on behalf of `*this` internal code, and it encountered a pipe-hosing error E.  E was then immediately</span></div>
<div class="line"><a id="l01269" name="l01269"></a><span class="lineno"> 1269</span><span class="comment">   *      emitted by `*this` via the `start()`-passed error handler.  Most public APIs from that point will no-op</span></div>
<div class="line"><a id="l01270" name="l01270"></a><span class="lineno"> 1270</span><span class="comment">   *      indicating prior pipe-hosing error.</span></div>
<div class="line"><a id="l01271" name="l01271"></a><span class="lineno"> 1271</span><span class="comment">   *   -# It might be a structured-layer error: that is the #Owned_channel is transmitting stuff fine still, but</span></div>
<div class="line"><a id="l01272" name="l01272"></a><span class="lineno"> 1272</span><span class="comment">   *      the logical contents of what has been received is corrupted or unexpected -- maybe the other side misbehaved,</span></div>
<div class="line"><a id="l01273" name="l01273"></a><span class="lineno"> 1273</span><span class="comment">   *      or there&#39;s a bug somewhere, maybe auth failed for some reason.  Blobs and handles could continue to be sent,</span></div>
<div class="line"><a id="l01274" name="l01274"></a><span class="lineno"> 1274</span><span class="comment">   *      but `*this` considers that bad, because the logical consistency of its world cannot be guaranteed.</span></div>
<div class="line"><a id="l01275" name="l01275"></a><span class="lineno"> 1275</span><span class="comment">   *      In this case `*this` internally generates an appropriate E (for example</span></div>
<div class="line"><a id="l01276" name="l01276"></a><span class="lineno"> 1276</span><span class="comment">   *      error::Code::S_STRUCT_CHANNEL_INTERNAL_PROTOCOL_BAD_AUTH) and emits it via the `start()`-passed error handler.</span></div>
<div class="line"><a id="l01277" name="l01277"></a><span class="lineno"> 1277</span><span class="comment">   *      Most public APIs from that point will no-op indicating prior pipe-hosing error.</span></div>
<div class="line"><a id="l01278" name="l01278"></a><span class="lineno"> 1278</span><span class="comment">   *</span></div>
<div class="line"><a id="l01279" name="l01279"></a><span class="lineno"> 1279</span><span class="comment">   * Type 1 is more straightforward to think about.  If a prior send emitted E due to #Owned_channel layer error E,</span></div>
<div class="line"><a id="l01280" name="l01280"></a><span class="lineno"> 1280</span><span class="comment">   * then async_end_sending() will simply emit E as well.  If a prior receive emitted E similarly, then</span></div>
<div class="line"><a id="l01281" name="l01281"></a><span class="lineno"> 1281</span><span class="comment">   * async_end_sending() may re-emit E as well or not; for Native_socket_stream (wherein internally there&#39;s a single</span></div>
<div class="line"><a id="l01282" name="l01282"></a><span class="lineno"> 1282</span><span class="comment">   * local-socket connection for both directions despite being full-duplex -- an error in one direction hoses the</span></div>
<div class="line"><a id="l01283" name="l01283"></a><span class="lineno"> 1283</span><span class="comment">   * other direction) yes; for the MQs (wherein the 2 pipes are fully decoupled) no.  That&#39;s not all that</span></div>
<div class="line"><a id="l01284" name="l01284"></a><span class="lineno"> 1284</span><span class="comment">   * straightforward already.</span></div>
<div class="line"><a id="l01285" name="l01285"></a><span class="lineno"> 1285</span><span class="comment">   *</span></div>
<div class="line"><a id="l01286" name="l01286"></a><span class="lineno"> 1286</span><span class="comment">   * Type 2 is even less straightforward.  In this case #Owned_channel is fine: so async_end_sending() will yield a</span></div>
<div class="line"><a id="l01287" name="l01287"></a><span class="lineno"> 1287</span><span class="comment">   * successful E most likely -- but meanwhile `*this` is generally behaving as if it&#39;s hosed; and indeed it is -- just</span></div>
<div class="line"><a id="l01288" name="l01288"></a><span class="lineno"> 1288</span><span class="comment">   * at the higher (strucuted) layer!</span></div>
<div class="line"><a id="l01289" name="l01289"></a><span class="lineno"> 1289</span><span class="comment">   *</span></div>
<div class="line"><a id="l01290" name="l01290"></a><span class="lineno"> 1290</span><span class="comment">   * The point of all this: It is pointless to worry about how async_end_sending()&#39;s emitted #Error_code relates to</span></div>
<div class="line"><a id="l01291" name="l01291"></a><span class="lineno"> 1291</span><span class="comment">   * what was emitted to the `start()`-passed error handler.  It may be the same thing; it may be different; and it may</span></div>
<div class="line"><a id="l01292" name="l01292"></a><span class="lineno"> 1292</span><span class="comment">   * well even be a falsy (success) #Error_code!  `async_end_sending(F)` -- again -- accomplishes a lower-level task:</span></div>
<div class="line"><a id="l01293" name="l01293"></a><span class="lineno"> 1293</span><span class="comment">   * it waits until any unsent messages are flushed out and then informs user via `F()`; and if this is at any stage</span></div>
<div class="line"><a id="l01294" name="l01294"></a><span class="lineno"> 1294</span><span class="comment">   * impossible (including immediately, due to prior error) then it indicates it right then via `F(E)` as well.</span></div>
<div class="line"><a id="l01295" name="l01295"></a><span class="lineno"> 1295</span><span class="comment">   * *They operate at different layers, even though their error may overlap depending on the situation.*</span></div>
<div class="line"><a id="l01296" name="l01296"></a><span class="lineno"> 1296</span><span class="comment">   * Hence, you should indeed invoke `async_end_sending(F)` from or after the error handler is invoked, then destroy</span></div>
<div class="line"><a id="l01297" name="l01297"></a><span class="lineno"> 1297</span><span class="comment">   * `*this` after `F()`.</span></div>
<div class="line"><a id="l01298" name="l01298"></a><span class="lineno"> 1298</span><span class="comment">   *   - If #Owned_channel out-pipe is hosed anyway, this will simply get to `*this` destruction stage immediately,</span></div>
<div class="line"><a id="l01299" name="l01299"></a><span class="lineno"> 1299</span><span class="comment">   *     which is fine: it&#39;s what one would do if they decide to not mess with async_end_sending() at all.</span></div>
<div class="line"><a id="l01300" name="l01300"></a><span class="lineno"> 1300</span><span class="comment">   *   - If #Owned_channel out-pipe is fine (despite something else -- possibly in-pipe, possibly structured protocol --</span></div>
<div class="line"><a id="l01301" name="l01301"></a><span class="lineno"> 1301</span><span class="comment">   *     being not-at-all-fine), this will in civilized fashion flush anything that might still be pending for whatever</span></div>
<div class="line"><a id="l01302" name="l01302"></a><span class="lineno"> 1302</span><span class="comment">   *     reason -- and gracefully inform the other side that, at any rate, this peer does not want to talk anymore.</span></div>
<div class="line"><a id="l01303" name="l01303"></a><span class="lineno"> 1303</span><span class="comment">   *     This reduces entropy; and at worst does not help anything but does not hurt.</span></div>
<div class="line"><a id="l01304" name="l01304"></a><span class="lineno"> 1304</span><span class="comment">   *</span></div>
<div class="line"><a id="l01305" name="l01305"></a><span class="lineno"> 1305</span><span class="comment">   * @todo Consider adding blocking `struc::Channel::sync_end_sending()`, possibly with timeout, since</span></div>
<div class="line"><a id="l01306" name="l01306"></a><span class="lineno"> 1306</span><span class="comment">   * `async_end_sending()` to completion is recommended (but not required) to execute at EOL of any struc::Channel.</span></div>
<div class="line"><a id="l01307" name="l01307"></a><span class="lineno"> 1307</span><span class="comment">   * The &quot;blocking&quot; part is good because it&#39;s convenient to not have to worry about handling completion with async</span></div>
<div class="line"><a id="l01308" name="l01308"></a><span class="lineno"> 1308</span><span class="comment">   * semantics boiler-plate.  The &quot;timeout&quot; part is good because it&#39;s a best-effort operation, when in a bad/slow</span></div>
<div class="line"><a id="l01309" name="l01309"></a><span class="lineno"> 1309</span><span class="comment">   * environment, and blocking -- even during deinit -- would be important to avoid.  For example,</span></div>
<div class="line"><a id="l01310" name="l01310"></a><span class="lineno"> 1310</span><span class="comment">   * the `Session` impls&#39; dtors perform this op; we don&#39;t want those to block for any significant time if at all</span></div>
<div class="line"><a id="l01311" name="l01311"></a><span class="lineno"> 1311</span><span class="comment">   * avoidable.  The reason it&#39;s a mere to-do currently is that a bug-free opposing struc::Channel should</span></div>
<div class="line"><a id="l01312" name="l01312"></a><span class="lineno"> 1312</span><span class="comment">   * not let would-block occur for any real length of time; so blocking is presumably unlikely.  Nevertheless.</span></div>
<div class="line"><a id="l01313" name="l01313"></a><span class="lineno"> 1313</span><span class="comment">   *</span></div>
<div class="line"><a id="l01314" name="l01314"></a><span class="lineno"> 1314</span><span class="comment">   * @tparam Task_err</span></div>
<div class="line"><a id="l01315" name="l01315"></a><span class="lineno"> 1315</span><span class="comment">   *         See transport::Channel::async_end_sending().</span></div>
<div class="line"><a id="l01316" name="l01316"></a><span class="lineno"> 1316</span><span class="comment">   * @param on_done_func</span></div>
<div class="line"><a id="l01317" name="l01317"></a><span class="lineno"> 1317</span><span class="comment">   *         See transport::Channel::async_end_sending().</span></div>
<div class="line"><a id="l01318" name="l01318"></a><span class="lineno"> 1318</span><span class="comment">   * @return See transport::Channel::async_end_sending().</span></div>
<div class="line"><a id="l01319" name="l01319"></a><span class="lineno"> 1319</span><span class="comment">   */</span></div>
<div class="line"><a id="l01320" name="l01320"></a><span class="lineno"> 1320</span>  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> Task_err&gt;</div>
<div class="line"><a id="l01321" name="l01321"></a><span class="lineno"> 1321</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#ab08057edd9832d94ea0e18a17c42200a">async_end_sending</a>(Task_err&amp;&amp; on_done_func);</div>
<div class="line"><a id="l01322" name="l01322"></a><span class="lineno"> 1322</span><span class="comment"></span> </div>
<div class="line"><a id="l01323" name="l01323"></a><span class="lineno"> 1323</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01324" name="l01324"></a><span class="lineno"> 1324</span><span class="comment">   * In log-in phase as server only: Registers the expectation of up to 1 *log-in request* in-message whose</span></div>
<div class="line"><a id="l01325" name="l01325"></a><span class="lineno"> 1325</span><span class="comment">   * #Msg_which equals `which`, firing the provided handler asynchronously once the *log-in response* does</span></div>
<div class="line"><a id="l01326" name="l01326"></a><span class="lineno"> 1326</span><span class="comment">   * arrive.  No-op and return `false` if expect_log_in_request() has already been invoked, if log-in phase is</span></div>
<div class="line"><a id="l01327" name="l01327"></a><span class="lineno"> 1327</span><span class="comment">   * not active or active in the client role, or if a prior error has hosed the owned transport::Channel.</span></div>
<div class="line"><a id="l01328" name="l01328"></a><span class="lineno"> 1328</span><span class="comment">   *</span></div>
<div class="line"><a id="l01329" name="l01329"></a><span class="lineno"> 1329</span><span class="comment">   * Informally the proper behavior is:</span></div>
<div class="line"><a id="l01330" name="l01330"></a><span class="lineno"> 1330</span><span class="comment">   *   -# Construct in log-in-as-server phase.</span></div>
<div class="line"><a id="l01331" name="l01331"></a><span class="lineno"> 1331</span><span class="comment">   *   -# Invoke expect_log_in_request().</span></div>
<div class="line"><a id="l01332" name="l01332"></a><span class="lineno"> 1332</span><span class="comment">   *   -# Await `on_log_in_req_func(X&amp;&amp;)` firing, where X is the log-in request.</span></div>
<div class="line"><a id="l01333" name="l01333"></a><span class="lineno"> 1333</span><span class="comment">   *   -# After `on_log_in_req_func(X&amp;&amp;)` handler: check X for correctness (such as process identity checks).</span></div>
<div class="line"><a id="l01334" name="l01334"></a><span class="lineno"> 1334</span><span class="comment">   *      If it fails checks, destroy `*this`; else:</span></div>
<div class="line"><a id="l01335" name="l01335"></a><span class="lineno"> 1335</span><span class="comment">   *   -# Fill out `X = this-&gt;create_msg()` (the log-in response) as needed via `X-&gt;body_root()`.</span></div>
<div class="line"><a id="l01336" name="l01336"></a><span class="lineno"> 1336</span><span class="comment">   *   -# `send(X)`.  The latter automatically moves `*this` to logged-in phase locally: the bulk of the</span></div>
<div class="line"><a id="l01337" name="l01337"></a><span class="lineno"> 1337</span><span class="comment">   *      API becomes available.</span></div>
<div class="line"><a id="l01338" name="l01338"></a><span class="lineno"> 1338</span><span class="comment">   *</span></div>
<div class="line"><a id="l01339" name="l01339"></a><span class="lineno"> 1339</span><span class="comment">   * @tparam On_msg_handler</span></div>
<div class="line"><a id="l01340" name="l01340"></a><span class="lineno"> 1340</span><span class="comment">   *         See expect_msg().</span></div>
<div class="line"><a id="l01341" name="l01341"></a><span class="lineno"> 1341</span><span class="comment">   * @param which</span></div>
<div class="line"><a id="l01342" name="l01342"></a><span class="lineno"> 1342</span><span class="comment">   *        See expect_msg().</span></div>
<div class="line"><a id="l01343" name="l01343"></a><span class="lineno"> 1343</span><span class="comment">   * @param on_log_in_req_func</span></div>
<div class="line"><a id="l01344" name="l01344"></a><span class="lineno"> 1344</span><span class="comment">   *        See above.</span></div>
<div class="line"><a id="l01345" name="l01345"></a><span class="lineno"> 1345</span><span class="comment">   * @return `true` on success; `false` due to one of the above conditions.</span></div>
<div class="line"><a id="l01346" name="l01346"></a><span class="lineno"> 1346</span><span class="comment">   */</span></div>
<div class="line"><a id="l01347" name="l01347"></a><span class="lineno"> 1347</span>  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_msg_handler&gt;</div>
<div class="line"><a id="l01348" name="l01348"></a><span class="lineno"> 1348</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a0054bbf18bc769b2a5b95f249e672c0a">expect_log_in_request</a>(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">Msg_which_in</a> which, On_msg_handler&amp;&amp; on_log_in_req_func);</div>
<div class="line"><a id="l01349" name="l01349"></a><span class="lineno"> 1349</span> </div>
<div class="line"><a id="l01350" name="l01350"></a><span class="lineno"> 1350</span><span class="keyword">private</span>:</div>
<div class="line"><a id="l01351" name="l01351"></a><span class="lineno"> 1351</span>  <span class="comment">// Types.</span></div>
<div class="line"><a id="l01352" name="l01352"></a><span class="lineno"> 1352</span><span class="comment"></span> </div>
<div class="line"><a id="l01353" name="l01353"></a><span class="lineno"> 1353</span><span class="comment">  /// Short-hand for #m_mutex (and similar) type.</span></div>
<div class="line"><a id="l01354" name="l01354"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ade399eda73424def3da0dd67596d2cff"> 1354</a></span><span class="comment"></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ade399eda73424def3da0dd67596d2cff">Mutex</a> = flow::util::Mutex_non_recursive;</div>
<div class="line"><a id="l01355" name="l01355"></a><span class="lineno"> 1355</span><span class="comment"></span> </div>
<div class="line"><a id="l01356" name="l01356"></a><span class="lineno"> 1356</span><span class="comment">  /// Short-hand for #Mutex lock.</span></div>
<div class="line"><a id="l01357" name="l01357"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25"> 1357</a></span><span class="comment"></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> = flow::util::Lock_guard&lt;Mutex&gt;;</div>
<div class="line"><a id="l01358" name="l01358"></a><span class="lineno"> 1358</span><span class="comment"></span> </div>
<div class="line"><a id="l01359" name="l01359"></a><span class="lineno"> 1359</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01360" name="l01360"></a><span class="lineno"> 1360</span><span class="comment">   * State in #m_sync_op_state, when a sync-op is in fact in progress, meaning #m_sync_op_state is not null.</span></div>
<div class="line"><a id="l01361" name="l01361"></a><span class="lineno"> 1361</span><span class="comment">   * See discussion in #m_sync_op_state doc header.</span></div>
<div class="line"><a id="l01362" name="l01362"></a><span class="lineno"> 1362</span><span class="comment">   */</span></div>
<div class="line"><a id="l01363" name="l01363"></a><span class="lineno"><a class="line" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html"> 1363</a></span>  <span class="keyword">struct </span><a class="code hl_struct" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html">Sync_op_state</a></div>
<div class="line"><a id="l01364" name="l01364"></a><span class="lineno"> 1364</span>  {</div>
<div class="line"><a id="l01365" name="l01365"></a><span class="lineno"> 1365</span>    <span class="comment">// Types.</span></div>
<div class="line"><a id="l01366" name="l01366"></a><span class="lineno"> 1366</span><span class="comment"></span> </div>
<div class="line"><a id="l01367" name="l01367"></a><span class="lineno"> 1367</span><span class="comment">    /// ID of each sync operation: a distinct value is used each time a `*this` is created/placed into #m_sync_op_state.</span></div>
<div class="line"><a id="l01368" name="l01368"></a><span class="lineno"><a class="line" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#a6b5142da7049fc212faff3914e69379b"> 1368</a></span><span class="comment"></span>    <span class="keyword">using </span><a class="code hl_typedef" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#a6b5142da7049fc212faff3914e69379b">id_t</a> = <span class="keywordtype">unsigned</span> int;</div>
<div class="line"><a id="l01369" name="l01369"></a><span class="lineno"> 1369</span><span class="comment"></span> </div>
<div class="line"><a id="l01370" name="l01370"></a><span class="lineno"> 1370</span><span class="comment">    /// A successul result of sync_request().</span></div>
<div class="line"><a id="l01371" name="l01371"></a><span class="lineno"><a class="line" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_1_1Request__result.html"> 1371</a></span><span class="comment"></span>    <span class="keyword">struct </span><a class="code hl_struct" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_1_1Request__result.html">Request_result</a></div>
<div class="line"><a id="l01372" name="l01372"></a><span class="lineno"> 1372</span>    {<span class="comment"></span></div>
<div class="line"><a id="l01373" name="l01373"></a><span class="lineno"> 1373</span><span class="comment">      /// Non-null response to out-message with ID Sync_op_state::m_originating_msg_id.</span></div>
<div class="line"><a id="l01374" name="l01374"></a><span class="lineno"><a class="line" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_1_1Request__result.html#a2c7cde843910f748296c2c9ec406d99b"> 1374</a></span><span class="comment"></span>      <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a> <a class="code hl_variable" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_1_1Request__result.html#a2c7cde843910f748296c2c9ec406d99b">m_rsp</a>;</div>
<div class="line"><a id="l01375" name="l01375"></a><span class="lineno"> 1375</span>    };</div>
<div class="line"><a id="l01376" name="l01376"></a><span class="lineno"> 1376</span> </div>
<div class="line"><a id="l01377" name="l01377"></a><span class="lineno"> 1377</span>    <span class="comment">// Data.</span></div>
<div class="line"><a id="l01378" name="l01378"></a><span class="lineno"> 1378</span><span class="comment"></span> </div>
<div class="line"><a id="l01379" name="l01379"></a><span class="lineno"> 1379</span><span class="comment">    /// See #id_t; used to check an arriving sync op result as belonging to the currently-waiting sync op.</span></div>
<div class="line"><a id="l01380" name="l01380"></a><span class="lineno"><a class="line" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#ad6f8e016b2abc3654e1915cc8c77c268"> 1380</a></span><span class="comment"></span>    <a class="code hl_typedef" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#a6b5142da7049fc212faff3914e69379b">id_t</a> <a class="code hl_variable" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#ad6f8e016b2abc3654e1915cc8c77c268">m_id</a>;</div>
<div class="line"><a id="l01381" name="l01381"></a><span class="lineno"> 1381</span><span class="comment"></span> </div>
<div class="line"><a id="l01382" name="l01382"></a><span class="lineno"> 1382</span><span class="comment">    /**</span></div>
<div class="line"><a id="l01383" name="l01383"></a><span class="lineno"> 1383</span><span class="comment">     * Current state of the in-progress sync-op (as of this writing, there is only sync_request()).</span></div>
<div class="line"><a id="l01384" name="l01384"></a><span class="lineno"> 1384</span><span class="comment">     *   - `monostate`: It is in progress; result unknown.</span></div>
<div class="line"><a id="l01385" name="l01385"></a><span class="lineno"> 1385</span><span class="comment">     *   - `Error_code`: It finished due to pipe-hosing error which is this truthy `Error_code`.</span></div>
<div class="line"><a id="l01386" name="l01386"></a><span class="lineno"> 1386</span><span class="comment">     *   - `Request_result`: It finished due to receiving response matching #m_id; that response is inside.</span></div>
<div class="line"><a id="l01387" name="l01387"></a><span class="lineno"> 1387</span><span class="comment">     * (If more sync-op APIs are added over time, more `variant` types may be added to express results of other</span></div>
<div class="line"><a id="l01388" name="l01388"></a><span class="lineno"> 1388</span><span class="comment">     * ops than sync_request().)</span></div>
<div class="line"><a id="l01389" name="l01389"></a><span class="lineno"> 1389</span><span class="comment">     */</span></div>
<div class="line"><a id="l01390" name="l01390"></a><span class="lineno"><a class="line" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#ac8c083b7c861d00e2f987a017fbe994e"> 1390</a></span>    std::variant&lt;std::monostate, Error_code, Request_result&gt; <a class="code hl_variable" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#ac8c083b7c861d00e2f987a017fbe994e">m_result_if_any</a>;</div>
<div class="line"><a id="l01391" name="l01391"></a><span class="lineno"> 1391</span><span class="comment"></span> </div>
<div class="line"><a id="l01392" name="l01392"></a><span class="lineno"> 1392</span><span class="comment">    /**</span></div>
<div class="line"><a id="l01393" name="l01393"></a><span class="lineno"> 1393</span><span class="comment">     * In-traffic processing thread W, having set #m_result_if_any to non-`monostate`, use</span></div>
<div class="line"><a id="l01394" name="l01394"></a><span class="lineno"> 1394</span><span class="comment">     * `m_op_done_signal.set_value(void)` to signal thread U to wake up from</span></div>
<div class="line"><a id="l01395" name="l01395"></a><span class="lineno"> 1395</span><span class="comment">     * `m_op_done_signal.get_future().wait*()`.  Thread U will then lock #m_mutex and examine the</span></div>
<div class="line"><a id="l01396" name="l01396"></a><span class="lineno"> 1396</span><span class="comment">     * situation:</span></div>
<div class="line"><a id="l01397" name="l01397"></a><span class="lineno"> 1397</span><span class="comment">     *   - If #m_result_if_any is `monostate`: Timeout.</span></div>
<div class="line"><a id="l01398" name="l01398"></a><span class="lineno"> 1398</span><span class="comment">     *   - If #m_result_if_any is `Error_code`: Got result in time, though it was pipe-hosing error.</span></div>
<div class="line"><a id="l01399" name="l01399"></a><span class="lineno"> 1399</span><span class="comment">     *   - If #m_result_if_any is something else: Got successful result in time.</span></div>
<div class="line"><a id="l01400" name="l01400"></a><span class="lineno"> 1400</span><span class="comment">     *</span></div>
<div class="line"><a id="l01401" name="l01401"></a><span class="lineno"> 1401</span><span class="comment">     * It then nullifies the entire Sync_op_state, unlocks mutex, and returns the result (timeout, error, or</span></div>
<div class="line"><a id="l01402" name="l01402"></a><span class="lineno"> 1402</span><span class="comment">     * success payload) from `sync_*()`.</span></div>
<div class="line"><a id="l01403" name="l01403"></a><span class="lineno"> 1403</span><span class="comment">     *</span></div>
<div class="line"><a id="l01404" name="l01404"></a><span class="lineno"> 1404</span><span class="comment">     * Note that #m_op_done_signal is not state, really, but 100% a signaling device.  Its purpose is</span></div>
<div class="line"><a id="l01405" name="l01405"></a><span class="lineno"> 1405</span><span class="comment">     * for thread W to wake thread U instead of waiting until the timeout period elapses, so that it may</span></div>
<div class="line"><a id="l01406" name="l01406"></a><span class="lineno"> 1406</span><span class="comment">     * return the result as quickly as it is available.</span></div>
<div class="line"><a id="l01407" name="l01407"></a><span class="lineno"> 1407</span><span class="comment">     */</span></div>
<div class="line"><a id="l01408" name="l01408"></a><span class="lineno"><a class="line" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#a5c49d5ee9989c5c0dc518868205687f0"> 1408</a></span>    boost::promise&lt;void&gt; <a class="code hl_variable" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#a5c49d5ee9989c5c0dc518868205687f0">m_op_done_signal</a>;</div>
<div class="line"><a id="l01409" name="l01409"></a><span class="lineno"> 1409</span>  }; <span class="comment">// struct Sync_op_state</span></div>
<div class="line"><a id="l01410" name="l01410"></a><span class="lineno"> 1410</span><span class="comment"></span> </div>
<div class="line"><a id="l01411" name="l01411"></a><span class="lineno"> 1411</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01412" name="l01412"></a><span class="lineno"> 1412</span><span class="comment">   * Concrete type corresponding to `On_msg_handler` template param: in-message handler.</span></div>
<div class="line"><a id="l01413" name="l01413"></a><span class="lineno"> 1413</span><span class="comment">   * We at times wrap that guy in a `shared_ptr` to minimize having to copy actual function objects -- we can</span></div>
<div class="line"><a id="l01414" name="l01414"></a><span class="lineno"> 1414</span><span class="comment">   * instead copy/move `shared_ptr&lt;On_msg_func&gt;` instead.</span></div>
<div class="line"><a id="l01415" name="l01415"></a><span class="lineno"> 1415</span><span class="comment">   */</span></div>
<div class="line"><a id="l01416" name="l01416"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a1df9dd26651017e61d7701bf3af42260"> 1416</a></span>  <span class="keyword">using </span><a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a1df9dd26651017e61d7701bf3af42260">On_msg_func</a> = <a class="code hl_typedef" href="namespaceipc.html#aa455c7f045059736578ca275fc1a851f">Function</a>&lt;void (<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a>&amp;&amp; msg)&gt;;</div>
<div class="line"><a id="l01417" name="l01417"></a><span class="lineno"> 1417</span> </div>
<div class="line"><a id="l01418" name="l01418"></a><span class="lineno"> 1418</span>  <span class="comment">// Methods.</span></div>
<div class="line"><a id="l01419" name="l01419"></a><span class="lineno"> 1419</span><span class="comment"></span> </div>
<div class="line"><a id="l01420" name="l01420"></a><span class="lineno"> 1420</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01421" name="l01421"></a><span class="lineno"> 1421</span><span class="comment">   * Implements the one-off expect-message APIs expect_msg() and expect_log_in_request().</span></div>
<div class="line"><a id="l01422" name="l01422"></a><span class="lineno"> 1422</span><span class="comment">   *</span></div>
<div class="line"><a id="l01423" name="l01423"></a><span class="lineno"> 1423</span><span class="comment">   * @tparam MSG_ELSE_LOG_IN</span></div>
<div class="line"><a id="l01424" name="l01424"></a><span class="lineno"> 1424</span><span class="comment">   *         `true` if expect_msg(), `false` is expect_log_in_request().</span></div>
<div class="line"><a id="l01425" name="l01425"></a><span class="lineno"> 1425</span><span class="comment">   * @tparam On_msg_handler</span></div>
<div class="line"><a id="l01426" name="l01426"></a><span class="lineno"> 1426</span><span class="comment">   *         See expect_msg() and buddy.</span></div>
<div class="line"><a id="l01427" name="l01427"></a><span class="lineno"> 1427</span><span class="comment">   * @param which</span></div>
<div class="line"><a id="l01428" name="l01428"></a><span class="lineno"> 1428</span><span class="comment">   *        See expect_msg() and buddy.</span></div>
<div class="line"><a id="l01429" name="l01429"></a><span class="lineno"> 1429</span><span class="comment">   * @param on_msg_func</span></div>
<div class="line"><a id="l01430" name="l01430"></a><span class="lineno"> 1430</span><span class="comment">   *        See expect_msg() and buddy.</span></div>
<div class="line"><a id="l01431" name="l01431"></a><span class="lineno"> 1431</span><span class="comment">   * @return See expect_msg() and buddy.</span></div>
<div class="line"><a id="l01432" name="l01432"></a><span class="lineno"> 1432</span><span class="comment">   */</span></div>
<div class="line"><a id="l01433" name="l01433"></a><span class="lineno"> 1433</span>  <span class="keyword">template</span>&lt;<span class="keywordtype">bool</span> MSG_ELSE_LOG_IN, <span class="keyword">typename</span> On_msg_handler&gt;</div>
<div class="line"><a id="l01434" name="l01434"></a><span class="lineno"> 1434</span>  <span class="keywordtype">bool</span> <a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1Channel.html#a8ca2772b0a657cb55f140a6273e528b9">expect_msg_impl</a>(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">Msg_which_in</a> which, On_msg_handler&amp;&amp; on_msg_func);</div>
<div class="line"><a id="l01435" name="l01435"></a><span class="lineno"> 1435</span> </div>
<div class="line"><a id="l01436" name="l01436"></a><span class="lineno"> 1436</span>  <span class="comment">// Data.</span></div>
<div class="line"><a id="l01437" name="l01437"></a><span class="lineno"> 1437</span><span class="comment"></span> </div>
<div class="line"><a id="l01438" name="l01438"></a><span class="lineno"> 1438</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01439" name="l01439"></a><span class="lineno"> 1439</span><span class="comment">   * Mutex causing, specifically, any sync_request() (or similar future methods) to execute in series and not</span></div>
<div class="line"><a id="l01440" name="l01440"></a><span class="lineno"> 1440</span><span class="comment">   * concurrently.</span></div>
<div class="line"><a id="l01441" name="l01441"></a><span class="lineno"> 1441</span><span class="comment">   *</span></div>
<div class="line"><a id="l01442" name="l01442"></a><span class="lineno"> 1442</span><span class="comment">   * @see also #m_mutex.</span></div>
<div class="line"><a id="l01443" name="l01443"></a><span class="lineno"> 1443</span><span class="comment">   *</span></div>
<div class="line"><a id="l01444" name="l01444"></a><span class="lineno"> 1444</span><span class="comment">   * This exists in addition to the more general #m_mutex, because a `sync_*()` blocking operation shall</span></div>
<div class="line"><a id="l01445" name="l01445"></a><span class="lineno"> 1445</span><span class="comment">   * allow other (non-blocking) APIs (such as send()) to execute immediately during the potential blocking-wait</span></div>
<div class="line"><a id="l01446" name="l01446"></a><span class="lineno"> 1446</span><span class="comment">   * inside a `sync_*()`.  So the general `m_mutex` cannot be locked during this way.</span></div>
<div class="line"><a id="l01447" name="l01447"></a><span class="lineno"> 1447</span><span class="comment">   *</span></div>
<div class="line"><a id="l01448" name="l01448"></a><span class="lineno"> 1448</span><span class="comment">   * To avoid deadlock #m_sync_op_mutex must be locked first, #m_mutex second.</span></div>
<div class="line"><a id="l01449" name="l01449"></a><span class="lineno"> 1449</span><span class="comment">   */</span></div>
<div class="line"><a id="l01450" name="l01450"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a0500d7dc635203ec6c32ca4b096a96c6"> 1450</a></span>  <span class="keyword">mutable</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ade399eda73424def3da0dd67596d2cff">Mutex</a> <a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#a0500d7dc635203ec6c32ca4b096a96c6">m_sync_op_mutex</a>;</div>
<div class="line"><a id="l01451" name="l01451"></a><span class="lineno"> 1451</span><span class="comment"></span> </div>
<div class="line"><a id="l01452" name="l01452"></a><span class="lineno"> 1452</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01453" name="l01453"></a><span class="lineno"> 1453</span><span class="comment">   * Mutex protecting the in-message/out-message state in `*this`.</span></div>
<div class="line"><a id="l01454" name="l01454"></a><span class="lineno"> 1454</span><span class="comment">   *</span></div>
<div class="line"><a id="l01455" name="l01455"></a><span class="lineno"> 1455</span><span class="comment">   * @see also #m_sync_op_mutex.</span></div>
<div class="line"><a id="l01456" name="l01456"></a><span class="lineno"> 1456</span><span class="comment">   *</span></div>
<div class="line"><a id="l01457" name="l01457"></a><span class="lineno"> 1457</span><span class="comment">   * The concurrency design is summarized in the impl section of our class doc header.</span></div>
<div class="line"><a id="l01458" name="l01458"></a><span class="lineno"> 1458</span><span class="comment">   *</span></div>
<div class="line"><a id="l01459" name="l01459"></a><span class="lineno"> 1459</span><span class="comment">   * In thread U, we generally forward to `m_sync_io.same_thing()`; and that `sync_io` core may request</span></div>
<div class="line"><a id="l01460" name="l01460"></a><span class="lineno"> 1460</span><span class="comment">   * an async-wait which we execute as a literaly `m_worker.async_wait(F)`, where `F()` -- from thread W now --</span></div>
<div class="line"><a id="l01461" name="l01461"></a><span class="lineno"> 1461</span><span class="comment">   * calls back into #m_sync_io code.  (Per `sync_io` pattern it&#39;s not a literal API call but can be considered one:</span></div>
<div class="line"><a id="l01462" name="l01462"></a><span class="lineno"> 1462</span><span class="comment">   * it is a callback `(*on_active_ev_func)()` which executes code within #m_sync_io.)  Formally speaking</span></div>
<div class="line"><a id="l01463" name="l01463"></a><span class="lineno"> 1463</span><span class="comment">   * sync_io::Channel forbids its APIs (including that quasi-API) being involved concurrently to each</span></div>
<div class="line"><a id="l01464" name="l01464"></a><span class="lineno"> 1464</span><span class="comment">   * other.  So we lock `m_mutex` both in thread U and within the thread-W `F()`.  Informally -- `m_sync_io`</span></div>
<div class="line"><a id="l01465" name="l01465"></a><span class="lineno"> 1465</span><span class="comment">   * accesses many of the same data structures when within `m_sync_io.same_thing()` as within the async-wait</span></div>
<div class="line"><a id="l01466" name="l01466"></a><span class="lineno"> 1466</span><span class="comment">   * handler `on_active_ev_func` it passes to us to async-wait on its behalf.  For example expect_msg() will</span></div>
<div class="line"><a id="l01467" name="l01467"></a><span class="lineno"> 1467</span><span class="comment">   * register a one-off expectation; whereas receiving an unstructured message that is decoded by</span></div>
<div class="line"><a id="l01468" name="l01468"></a><span class="lineno"> 1468</span><span class="comment">   * #m_sync_io as satisfying that expectation will unregister that one-off expectation in `m_sync_io`&#39;s internal map.</span></div>
<div class="line"><a id="l01469" name="l01469"></a><span class="lineno"> 1469</span><span class="comment">   *</span></div>
<div class="line"><a id="l01470" name="l01470"></a><span class="lineno"> 1470</span><span class="comment">   * Moreover we explicitly allow concurrent calls on the same `*this`.</span></div>
<div class="line"><a id="l01471" name="l01471"></a><span class="lineno"> 1471</span><span class="comment">   * All of the above means methods dealing with mutable state shall lock this #m_mutex around most of</span></div>
<div class="line"><a id="l01472" name="l01472"></a><span class="lineno"> 1472</span><span class="comment">   * the code (with the notable exception of the potentially-blocking wait inside sync_request() -- which instead</span></div>
<div class="line"><a id="l01473" name="l01473"></a><span class="lineno"> 1473</span><span class="comment">   * has a locked-section before the wait and another after).</span></div>
<div class="line"><a id="l01474" name="l01474"></a><span class="lineno"> 1474</span><span class="comment">   *</span></div>
<div class="line"><a id="l01475" name="l01475"></a><span class="lineno"> 1475</span><span class="comment">   * ### Perf ###</span></div>
<div class="line"><a id="l01476" name="l01476"></a><span class="lineno"> 1476</span><span class="comment">   * It&#39;s similar to such discussions in Native_socket_stream for example.  The additional items here are as follows.</span></div>
<div class="line"><a id="l01477" name="l01477"></a><span class="lineno"> 1477</span><span class="comment">   *   - We operate potentially 2 pipes&#39; logic in the same thread.  Theoretically all else being equal handling</span></div>
<div class="line"><a id="l01478" name="l01478"></a><span class="lineno"> 1478</span><span class="comment">   *     a blob in one could delay handling a blob+possible native handle in the other and thus add latency.  However</span></div>
<div class="line"><a id="l01479" name="l01479"></a><span class="lineno"> 1479</span><span class="comment">   *     that is not really how the #Sync_io_obj uses them: they&#39;re really doing stuff in parallel vast majority of</span></div>
<div class="line"><a id="l01480" name="l01480"></a><span class="lineno"> 1480</span><span class="comment">   *     the time.  It uses the native-handle pipe (if any!) only to transmit native handles, basically.  I&#39;ll</span></div>
<div class="line"><a id="l01481" name="l01481"></a><span class="lineno"> 1481</span><span class="comment">   *     skip the pontification about why this is unlikely to create much concurrent traffic -- leaving that as</span></div>
<div class="line"><a id="l01482" name="l01482"></a><span class="lineno"> 1482</span><span class="comment">   *     an exercise to the reader.</span></div>
<div class="line"><a id="l01483" name="l01483"></a><span class="lineno"> 1483</span><span class="comment">   *   - Native_socket_stream allows independent -- concurrent -- operation of the out-pipe versus the in-pipe.</span></div>
<div class="line"><a id="l01484" name="l01484"></a><span class="lineno"> 1484</span><span class="comment">   *     E.g., `send_blob()` can run concurrently to receipt of an in-message due to `async_receive_blob()`.</span></div>
<div class="line"><a id="l01485" name="l01485"></a><span class="lineno"> 1485</span><span class="comment">   *     In our case the #Sync_io_obj forbids any such thing, and indeed we use just one #m_mutex.</span></div>
<div class="line"><a id="l01486" name="l01486"></a><span class="lineno"> 1486</span><span class="comment">   *     (Native_socket_stream has 2, one per direction: one in Async_adapter_sender, one in Async_adapter_receiver.)</span></div>
<div class="line"><a id="l01487" name="l01487"></a><span class="lineno"> 1487</span><span class="comment">   *     We cannot really do otherwise.  (Possibly send() -- not async_request() -- could be factored out.  Maybe</span></div>
<div class="line"><a id="l01488" name="l01488"></a><span class="lineno"> 1488</span><span class="comment">   *     look into it.  Not an official to-do yet.)  Does this create lock contention?  It could in limited</span></div>
<div class="line"><a id="l01489" name="l01489"></a><span class="lineno"> 1489</span><span class="comment">   *     circumstances: if the user protocol is not of ping-pong fashion but rather involving heavy downloads and</span></div>
<div class="line"><a id="l01490" name="l01490"></a><span class="lineno"> 1490</span><span class="comment">   *     uploads concurrently.  If this actually presents a problem in practice we could look into</span></div>
<div class="line"><a id="l01491" name="l01491"></a><span class="lineno"> 1491</span><span class="comment">   *     allowing more concurrency in #Sync_io_obj and then make use of it in `*this` by adding more mutexes</span></div>
<div class="line"><a id="l01492" name="l01492"></a><span class="lineno"> 1492</span><span class="comment">   *     and more complex logic.</span></div>
<div class="line"><a id="l01493" name="l01493"></a><span class="lineno"> 1493</span><span class="comment">   */</span></div>
<div class="line"><a id="l01494" name="l01494"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a01c90903e715ebcf64d8b5ea0d114bc0"> 1494</a></span>  <span class="keyword">mutable</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ade399eda73424def3da0dd67596d2cff">Mutex</a> <a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#a01c90903e715ebcf64d8b5ea0d114bc0">m_mutex</a>;</div>
<div class="line"><a id="l01495" name="l01495"></a><span class="lineno"> 1495</span><span class="comment"></span> </div>
<div class="line"><a id="l01496" name="l01496"></a><span class="lineno"> 1496</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01497" name="l01497"></a><span class="lineno"> 1497</span><span class="comment">   * The current state of the blocking sync-op mechanism; a `variant` that broadly describes the state as:</span></div>
<div class="line"><a id="l01498" name="l01498"></a><span class="lineno"> 1498</span><span class="comment">   * no sync-op in progress, sync-op in progress sans result, sync-op in progress with result that has not yet</span></div>
<div class="line"><a id="l01499" name="l01499"></a><span class="lineno"> 1499</span><span class="comment">   * been returned to user (sync-op almost over).  Please read on.</span></div>
<div class="line"><a id="l01500" name="l01500"></a><span class="lineno"> 1500</span><span class="comment">   *</span></div>
<div class="line"><a id="l01501" name="l01501"></a><span class="lineno"> 1501</span><span class="comment">   * ### Design of blocking sync-op mechanism ###</span></div>
<div class="line"><a id="l01502" name="l01502"></a><span class="lineno"> 1502</span><span class="comment">   * A `sync_*()` operation is one that synchronously awaits in-traffic of some kind and returns some result</span></div>
<div class="line"><a id="l01503" name="l01503"></a><span class="lineno"> 1503</span><span class="comment">   * based on the contents of this in-traffic, or an error if the pipe got hosed during the wait (in which</span></div>
<div class="line"><a id="l01504" name="l01504"></a><span class="lineno"> 1504</span><span class="comment">   * case that error is *not* reported to the regular on-error handler, in the same way that non-blocking send()</span></div>
<div class="line"><a id="l01505" name="l01505"></a><span class="lineno"> 1505</span><span class="comment">   * returns a pipe-hosing error).  In addition it is subject to a (possibly infinite) user-specified timeout;</span></div>
<div class="line"><a id="l01506" name="l01506"></a><span class="lineno"> 1506</span><span class="comment">   * if neither a successful result or an error appears by that time, then that fact is returned by `sync_*()`.</span></div>
<div class="line"><a id="l01507" name="l01507"></a><span class="lineno"> 1507</span><span class="comment">   * After `sync_*()` returns, further in-pipe errors again go to the regular on-error handler until</span></div>
<div class="line"><a id="l01508" name="l01508"></a><span class="lineno"> 1508</span><span class="comment">   * a `sync_*()` op starts (from thread U/W).</span></div>
<div class="line"><a id="l01509" name="l01509"></a><span class="lineno"> 1509</span><span class="comment">   *</span></div>
<div class="line"><a id="l01510" name="l01510"></a><span class="lineno"> 1510</span><span class="comment">   * As of this writing there is only one such op: sync_request().  In this discussion we discuss that one</span></div>
<div class="line"><a id="l01511" name="l01511"></a><span class="lineno"> 1511</span><span class="comment">   * specifically (while mentally considering how it might be generalized in the future; the mechanism is designed</span></div>
<div class="line"><a id="l01512" name="l01512"></a><span class="lineno"> 1512</span><span class="comment">   * hopefully in such a way as to make it not-too-tough to extend to other `sync_*()`s; but we don&#39;t want to</span></div>
<div class="line"><a id="l01513" name="l01513"></a><span class="lineno"> 1513</span><span class="comment">   * over-engineer this and/or confuse the reader needlessly).</span></div>
<div class="line"><a id="l01514" name="l01514"></a><span class="lineno"> 1514</span><span class="comment">   *</span></div>
<div class="line"><a id="l01515" name="l01515"></a><span class="lineno"> 1515</span><span class="comment">   * It is a specific documented requirement that sync_request() may be invoked concurrently with itself.  (Also it</span></div>
<div class="line"><a id="l01516" name="l01516"></a><span class="lineno"> 1516</span><span class="comment">   * is explicitly *not* to be invoked from thread W (i.e., directly from an on-receive handler), as that would</span></div>
<div class="line"><a id="l01517" name="l01517"></a><span class="lineno"> 1517</span><span class="comment">   * delay other handlers&#39; execution; so it is to be invoked from thread U only.)  Hence we use a dedicated</span></div>
<div class="line"><a id="l01518" name="l01518"></a><span class="lineno"> 1518</span><span class="comment">   * #m_sync_op_mutex so that, at any point in time for `*this`, there is either no sync_request() running,</span></div>
<div class="line"><a id="l01519" name="l01519"></a><span class="lineno"> 1519</span><span class="comment">   * or there is exactly one running -- though other APIs might be -- and moreover `*this` is safe from being destroyed.</span></div>
<div class="line"><a id="l01520" name="l01520"></a><span class="lineno"> 1520</span><span class="comment">   *</span></div>
<div class="line"><a id="l01521" name="l01521"></a><span class="lineno"> 1521</span><span class="comment">   * @note There is a to-do as of this writing in the sync_request() doc header to allow for one</span></div>
<div class="line"><a id="l01522" name="l01522"></a><span class="lineno"> 1522</span><span class="comment">   *       `sync_request()` to not have to block the initiation of another until it fully completes.</span></div>
<div class="line"><a id="l01523" name="l01523"></a><span class="lineno"> 1523</span><span class="comment">   *       To achieve this we might have not one #m_sync_op_state (or zero, via `optional`) but a set of 0+ of them.</span></div>
<div class="line"><a id="l01524" name="l01524"></a><span class="lineno"> 1524</span><span class="comment">   *       The algorithm for each one would remain essentially the same as now.  #m_sync_op_mutex can then go away.</span></div>
<div class="line"><a id="l01525" name="l01525"></a><span class="lineno"> 1525</span><span class="comment">   *</span></div>
<div class="line"><a id="l01526" name="l01526"></a><span class="lineno"> 1526</span><span class="comment">   * sync_request() first performs essentially a normal non-blocking async_request(), and if that succeeds the blocking</span></div>
<div class="line"><a id="l01527" name="l01527"></a><span class="lineno"> 1527</span><span class="comment">   * part begins.  `m_sync_op_state-&gt;m_op_done_signal` is initialized to a promise and a future-wait (with timeout)</span></div>
<div class="line"><a id="l01528" name="l01528"></a><span class="lineno"> 1528</span><span class="comment">   * begins in thread U.  Meanwhile in the background `*this` is operating normally,</span></div>
<div class="line"><a id="l01529" name="l01529"></a><span class="lineno"> 1529</span><span class="comment">   * handling all in-traffic.  If it gets a successful result (namely a response</span></div>
<div class="line"><a id="l01530" name="l01530"></a><span class="lineno"> 1530</span><span class="comment">   * to the particular message the nb-send sent -- not some other in-traffic, which is</span></div>
<div class="line"><a id="l01531" name="l01531"></a><span class="lineno"> 1531</span><span class="comment">   * handled normally) while such a wait is in progress in thread U, it loads the result into #m_sync_op_state and</span></div>
<div class="line"><a id="l01532" name="l01532"></a><span class="lineno"> 1532</span><span class="comment">   * tickles thread U to stop waiting via `m_sync_op_done`.  If it gets any pipe-hosing error, it loads that</span></div>
<div class="line"><a id="l01533" name="l01533"></a><span class="lineno"> 1533</span><span class="comment">   * different result and similarly tickles the `promise`.  If the timeout happens first, the promise is destroyed,</span></div>
<div class="line"><a id="l01534" name="l01534"></a><span class="lineno"> 1534</span><span class="comment">   * and more importantly #m_sync_op_state is reset to steady state.</span></div>
<div class="line"><a id="l01535" name="l01535"></a><span class="lineno"> 1535</span><span class="comment">   *</span></div>
<div class="line"><a id="l01536" name="l01536"></a><span class="lineno"> 1536</span><span class="comment">   * (After this, an error is handled normally through on-error handler.  More interestingly, suppose</span></div>
<div class="line"><a id="l01537" name="l01537"></a><span class="lineno"> 1537</span><span class="comment">   * a response to the formerly-expecting-response-but-now-timed-out out-message does arrive later.</span></div>
<div class="line"><a id="l01538" name="l01538"></a><span class="lineno"> 1538</span><span class="comment">   * That out-message ID is still registered in #m_sync_io as expecting a response due to</span></div>
<div class="line"><a id="l01539" name="l01539"></a><span class="lineno"> 1539</span><span class="comment">   * a sync-op; but our special internal handler for that response detects that there is no longer a sync-request in</span></div>
<div class="line"><a id="l01540" name="l01540"></a><span class="lineno"> 1540</span><span class="comment">   * progress, or if there is it is for a different out-message ID -- so it timed out.  So it is just dropped.</span></div>
<div class="line"><a id="l01541" name="l01541"></a><span class="lineno"> 1541</span><span class="comment">   *</span></div>
<div class="line"><a id="l01542" name="l01542"></a><span class="lineno"> 1542</span><span class="comment">   * That&#39;s broadly how it works.  Now specifically here are the states in the state machine.  Note this machine is</span></div>
<div class="line"><a id="l01543" name="l01543"></a><span class="lineno"> 1543</span><span class="comment">   * protected by #m_mutex.</span></div>
<div class="line"><a id="l01544" name="l01544"></a><span class="lineno"> 1544</span><span class="comment">   *   - Null (steady state, no sync-op in progress): #m_sync_op_state is empty/null.  sync_request() is not executing,</span></div>
<div class="line"><a id="l01545" name="l01545"></a><span class="lineno"> 1545</span><span class="comment">   *     or is running before or after the blocking part.</span></div>
<div class="line"><a id="l01546" name="l01546"></a><span class="lineno"> 1546</span><span class="comment">   *   - In-progress, no result: #m_sync_op_state is non-null, and its Sync_op_state::m_result_if_any</span></div>
<div class="line"><a id="l01547" name="l01547"></a><span class="lineno"> 1547</span><span class="comment">   *     holds `monostate`: sync_request() is waiting on the promise inside #m_sync_op_state, subject to a timeout,</span></div>
<div class="line"><a id="l01548" name="l01548"></a><span class="lineno"> 1548</span><span class="comment">   *     and no result has yet been received.  (Or it is just about to enter this wait having unlocked mutex,</span></div>
<div class="line"><a id="l01549" name="l01549"></a><span class="lineno"> 1549</span><span class="comment">   *     or it had just exited it and is about to lock mutex.)</span></div>
<div class="line"><a id="l01550" name="l01550"></a><span class="lineno"> 1550</span><span class="comment">   *     - sync_request() has permanently set Sync_op_state::m_id to equal a unique ID and captured this in the</span></div>
<div class="line"><a id="l01551" name="l01551"></a><span class="lineno"> 1551</span><span class="comment">   *       internal response handler, so it can be checked against `m_id` later.</span></div>
<div class="line"><a id="l01552" name="l01552"></a><span class="lineno"> 1552</span><span class="comment">   *   - In-progress, with result: #m_sync_op_state is non-null, and its Sync_op_state::m_result_if_any</span></div>
<div class="line"><a id="l01553" name="l01553"></a><span class="lineno"> 1553</span><span class="comment">   *     holds *not* `monostate` (but rather either a truthy `Error_code` indicating error; or else the response):</span></div>
<div class="line"><a id="l01554" name="l01554"></a><span class="lineno"> 1554</span><span class="comment">   *     sync_request() is as in the previous bullet.  However, since the result is ready, the code</span></div>
<div class="line"><a id="l01555" name="l01555"></a><span class="lineno"> 1555</span><span class="comment">   *     (in thread W) -- having detected the result condition -- will, just before unlocking the mutex</span></div>
<div class="line"><a id="l01556" name="l01556"></a><span class="lineno"> 1556</span><span class="comment">   *     having set the result in Sync_op_state::m_result_if_any, tickle the promise, waking up the wait</span></div>
<div class="line"><a id="l01557" name="l01557"></a><span class="lineno"> 1557</span><span class="comment">   *     in sync_request().</span></div>
<div class="line"><a id="l01558" name="l01558"></a><span class="lineno"> 1558</span><span class="comment">   *     - Suppose sync_request() wins the race by timing out first.  It will then set #m_sync_op_state to null</span></div>
<div class="line"><a id="l01559" name="l01559"></a><span class="lineno"> 1559</span><span class="comment">   *       (and return timeout to caller, all in thread U).</span></div>
<div class="line"><a id="l01560" name="l01560"></a><span class="lineno"> 1560</span><span class="comment">   *       - If an error occurs in thread W subsequently, we&#39;ll see there&#39;s no sync-op in progress and</span></div>
<div class="line"><a id="l01561" name="l01561"></a><span class="lineno"> 1561</span><span class="comment">   *         report error normally via on-error handler.</span></div>
<div class="line"><a id="l01562" name="l01562"></a><span class="lineno"> 1562</span><span class="comment">   *       - If response to the ID arrives, we&#39;ll see there&#39;s no sync-op</span></div>
<div class="line"><a id="l01563" name="l01563"></a><span class="lineno"> 1563</span><span class="comment">   *         in progress, or a new one is in progress but with different `m_id`, so it is</span></div>
<div class="line"><a id="l01564" name="l01564"></a><span class="lineno"> 1564</span><span class="comment">   *         a late-arrival.  Then we drop it.</span></div>
<div class="line"><a id="l01565" name="l01565"></a><span class="lineno"> 1565</span><span class="comment">   */</span></div>
<div class="line"><a id="l01566" name="l01566"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ab40d8133d53135bcc41a12cc27fc8e13"> 1566</a></span>  std::optional&lt;Sync_op_state&gt; <a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#ab40d8133d53135bcc41a12cc27fc8e13">m_sync_op_state</a>;</div>
<div class="line"><a id="l01567" name="l01567"></a><span class="lineno"> 1567</span><span class="comment"></span> </div>
<div class="line"><a id="l01568" name="l01568"></a><span class="lineno"> 1568</span><span class="comment">  /// Next unique ID for Sync_op_state::m_id.</span></div>
<div class="line"><a id="l01569" name="l01569"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#abb0ed2e666191dd85e543072077bf38b"> 1569</a></span><span class="comment"></span>  <span class="keyword">typename</span> <a class="code hl_typedef" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#a6b5142da7049fc212faff3914e69379b">Sync_op_state::id_t</a> <a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#abb0ed2e666191dd85e543072077bf38b">m_sync_op_state_id</a>;</div>
<div class="line"><a id="l01570" name="l01570"></a><span class="lineno"> 1570</span><span class="comment"></span> </div>
<div class="line"><a id="l01571" name="l01571"></a><span class="lineno"> 1571</span><span class="comment">  /// Analogous to Async_adapter_sender::m_end_sending_on_done_func_or_empty.</span></div>
<div class="line"><a id="l01572" name="l01572"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a5e905a57052ba370d8d2f45a361982d8"> 1572</a></span><span class="comment"></span>  flow::async::Task_asio_err <a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#a5e905a57052ba370d8d2f45a361982d8">m_snd_end_sending_on_done_func_or_empty</a>;</div>
<div class="line"><a id="l01573" name="l01573"></a><span class="lineno"> 1573</span><span class="comment"></span> </div>
<div class="line"><a id="l01574" name="l01574"></a><span class="lineno"> 1574</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01575" name="l01575"></a><span class="lineno"> 1575</span><span class="comment">   * Thread W used to (1) fire user-provided handlers and (2) perform any async work requested by</span></div>
<div class="line"><a id="l01576" name="l01576"></a><span class="lineno"> 1576</span><span class="comment">   * #m_sync_io.</span></div>
<div class="line"><a id="l01577" name="l01577"></a><span class="lineno"> 1577</span><span class="comment">   */</span></div>
<div class="line"><a id="l01578" name="l01578"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a2184077da7828589d20d7f92a31a6394"> 1578</a></span>  flow::async::Single_thread_task_loop <a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#a2184077da7828589d20d7f92a31a6394">m_worker</a>;</div>
<div class="line"><a id="l01579" name="l01579"></a><span class="lineno"> 1579</span><span class="comment"></span> </div>
<div class="line"><a id="l01580" name="l01580"></a><span class="lineno"> 1580</span><span class="comment">  /**</span></div>
<div class="line"><a id="l01581" name="l01581"></a><span class="lineno"> 1581</span><span class="comment">   * The core `struc::Channel` engine, implementing the `sync_io` pattern (see util::sync_io doc header).</span></div>
<div class="line"><a id="l01582" name="l01582"></a><span class="lineno"> 1582</span><span class="comment">   * See our class doc header for overview of how we use it (the aforementioned `sync_io` doc header talks about</span></div>
<div class="line"><a id="l01583" name="l01583"></a><span class="lineno"> 1583</span><span class="comment">   * the `sync_io` pattern generally).</span></div>
<div class="line"><a id="l01584" name="l01584"></a><span class="lineno"> 1584</span><span class="comment">   *</span></div>
<div class="line"><a id="l01585" name="l01585"></a><span class="lineno"> 1585</span><span class="comment">   * Thus, #m_sync_io is the synchronous engine that we use to perform our work in our asynchronous boost.asio</span></div>
<div class="line"><a id="l01586" name="l01586"></a><span class="lineno"> 1586</span><span class="comment">   * loop running in thread W (#m_worker) while collaborating with user thread(s) a/k/a thread U.</span></div>
<div class="line"><a id="l01587" name="l01587"></a><span class="lineno"> 1587</span><span class="comment">   * (Recall that the user may choose to set up their own event loop/thread(s) --</span></div>
<div class="line"><a id="l01588" name="l01588"></a><span class="lineno"> 1588</span><span class="comment">   * boost.asio-based or otherwise -- and use their own equivalent of an #m_sync_io instead.)</span></div>
<div class="line"><a id="l01589" name="l01589"></a><span class="lineno"> 1589</span><span class="comment">   *</span></div>
<div class="line"><a id="l01590" name="l01590"></a><span class="lineno"> 1590</span><span class="comment">   * ### Order subtlety versus `m_worker` ###</span></div>
<div class="line"><a id="l01591" name="l01591"></a><span class="lineno"> 1591</span><span class="comment">   * When constructing #m_sync_io, we need the `Task_engine` from #m_worker.  On the other hand tasks operating</span></div>
<div class="line"><a id="l01592" name="l01592"></a><span class="lineno"> 1592</span><span class="comment">   * in #m_worker access #m_sync_io.  So in destructor it is important to `m_worker.stop()` explicitly, so that</span></div>
<div class="line"><a id="l01593" name="l01593"></a><span class="lineno"> 1593</span><span class="comment">   * the latter is no longer a factor.  Then when automatic destruction occurs in the opposite order of</span></div>
<div class="line"><a id="l01594" name="l01594"></a><span class="lineno"> 1594</span><span class="comment">   * creation, the fact that #m_sync_io is destroyed before #m_worker has no bad effect.</span></div>
<div class="line"><a id="l01595" name="l01595"></a><span class="lineno"> 1595</span><span class="comment">   */</span></div>
<div class="line"><a id="l01596" name="l01596"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#aefee55a9e754a63ce52766d6c65df92c"> 1596</a></span>  <a class="code hl_class" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html">Sync_io_obj</a> <a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#aefee55a9e754a63ce52766d6c65df92c">m_sync_io</a>;</div>
<div class="line"><a id="l01597" name="l01597"></a><span class="lineno"> 1597</span>}; <span class="comment">// class Channel</span></div>
<div class="line"><a id="l01598" name="l01598"></a><span class="lineno"> 1598</span> </div>
<div class="line"><a id="l01599" name="l01599"></a><span class="lineno"> 1599</span><span class="comment">// Free functions: in *_fwd.hpp.</span></div>
<div class="line"><a id="l01600" name="l01600"></a><span class="lineno"> 1600</span> </div>
<div class="line"><a id="l01601" name="l01601"></a><span class="lineno"> 1601</span><span class="comment">// Template implementations.</span></div>
<div class="line"><a id="l01602" name="l01602"></a><span class="lineno"> 1602</span><span class="comment"></span> </div>
<div class="line"><a id="l01603" name="l01603"></a><span class="lineno"> 1603</span><span class="comment">/**</span></div>
<div class="line"><a id="l01604" name="l01604"></a><span class="lineno"> 1604</span><span class="comment"> * Internally used macro; public API users should disregard.</span></div>
<div class="line"><a id="l01605" name="l01605"></a><span class="lineno"> 1605</span><span class="comment"> * @internal</span></div>
<div class="line"><a id="l01606" name="l01606"></a><span class="lineno"> 1606</span><span class="comment"> * Convenience macro for *this* file only: non-inline class template methods are hideous to read (+ write), when there</span></div>
<div class="line"><a id="l01607" name="l01607"></a><span class="lineno"> 1607</span><span class="comment"> * are so many template parameters.  These are `undef`-ed at the end of the file.</span></div>
<div class="line"><a id="l01608" name="l01608"></a><span class="lineno"> 1608</span><span class="comment"> *</span></div>
<div class="line"><a id="l01609" name="l01609"></a><span class="lineno"> 1609</span><span class="comment"> * ### Doxygen notes ###</span></div>
<div class="line"><a id="l01610" name="l01610"></a><span class="lineno"> 1610</span><span class="comment"> * Ideally these would not output Doxygen documentation, but then Doxygen produces a warning which we cannot accept.</span></div>
<div class="line"><a id="l01611" name="l01611"></a><span class="lineno"> 1611</span><span class="comment"> * `cond` + `endcond` Doxygen directives can easily make Doxygen ignore them; but then another problem pops up:</span></div>
<div class="line"><a id="l01612" name="l01612"></a><span class="lineno"> 1612</span><span class="comment"> * It sees the method bodies and gets confused by what it sees as non-existent class name `CLASS_...` and warns about</span></div>
<div class="line"><a id="l01613" name="l01613"></a><span class="lineno"> 1613</span><span class="comment"> * *that*.  The Doxyfile `MACRO_EXPANSION = YES` tag setting eliminates that problem -- but then `cond` + `endcond`</span></div>
<div class="line"><a id="l01614" name="l01614"></a><span class="lineno"> 1614</span><span class="comment"> * around this makes it also ignore the `&quot;#define&quot;` which brings back the latter warning.  Hence, as far as we</span></div>
<div class="line"><a id="l01615" name="l01615"></a><span class="lineno"> 1615</span><span class="comment"> * can tell with Doxygen 1.9.3, no choice but to Doxygen-document these.</span></div>
<div class="line"><a id="l01616" name="l01616"></a><span class="lineno"> 1616</span><span class="comment"> *</span></div>
<div class="line"><a id="l01617" name="l01617"></a><span class="lineno"> 1617</span><span class="comment"> * @todo Look over the rest of the code base -- possibly in Flow too -- and apply the `define TEMPLATE_`</span></div>
<div class="line"><a id="l01618" name="l01618"></a><span class="lineno"> 1618</span><span class="comment"> * + `define CLASS_` technique where it&#39;d be subjectively beneficial.</span></div>
<div class="line"><a id="l01619" name="l01619"></a><span class="lineno"> 1619</span><span class="comment"> */</span></div>
<div class="line"><a id="l01620" name="l01620"></a><span class="lineno"><a class="line" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb"> 1620</a></span><span class="preprocessor">#define TEMPLATE_STRUCTURED_CHANNEL \</span></div>
<div class="line"><a id="l01621" name="l01621"></a><span class="lineno"> 1621</span><span class="preprocessor">  template&lt;typename Channel_obj, typename Message_body, \</span></div>
<div class="line"><a id="l01622" name="l01622"></a><span class="lineno"> 1622</span><span class="preprocessor">           typename Struct_builder_config, typename Struct_reader_config&gt;</span><span class="comment"></span></div>
<div class="line"><a id="l01623" name="l01623"></a><span class="lineno"> 1623</span><span class="comment">/// See nearby `TEMPLATE_...` macro; same deal here.</span></div>
<div class="line"><a id="l01624" name="l01624"></a><span class="lineno"><a class="line" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a5313383b4bb7158e2f65d89690348f04"> 1624</a></span><span class="comment"></span><span class="preprocessor">#define CLASS_STRUCTURED_CHANNEL \</span></div>
<div class="line"><a id="l01625" name="l01625"></a><span class="lineno"> 1625</span><span class="preprocessor">  Channel&lt;Channel_obj, Message_body, Struct_builder_config, Struct_reader_config&gt;</span></div>
<div class="line"><a id="l01626" name="l01626"></a><span class="lineno"> 1626</span> </div>
<div class="line"><a id="l01627" name="l01627"></a><span class="lineno"> 1627</span> </div>
<div class="line"><a id="l01628" name="l01628"></a><span class="lineno"> 1628</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l01629" name="l01629"></a><span class="lineno"> 1629</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span>... Ctor_args&gt;</div>
<div class="line"><a id="l01630" name="l01630"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#abe73bfa20ca0207ac8aa63d26d54de83"> 1630</a></span><a class="code hl_typedef" href="namespaceipc_1_1transport_1_1struc_1_1shm_1_1classic.html#ac543b500a85f556564e592cbbefb6185">CLASS_STRUCTURED_CHANNEL::Channel</a>(flow::log::Logger* logger_ptr,</div>
<div class="line"><a id="l01631" name="l01631"></a><span class="lineno"> 1631</span>                                  Channel_obj&amp;&amp; channel, Ctor_args&amp;&amp;... ctor_args) :</div>
<div class="line"><a id="l01632" name="l01632"></a><span class="lineno"> 1632</span>  flow::log::Log_context(logger_ptr, <a class="code hl_enumeration" href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7">Log_component</a>::S_TRANSPORT),</div>
<div class="line"><a id="l01633" name="l01633"></a><span class="lineno"> 1633</span>  m_sync_op_state_id(0),</div>
<div class="line"><a id="l01634" name="l01634"></a><span class="lineno"> 1634</span>  m_worker(get_logger(), <span class="comment">// Thread W started just below.</span></div>
<div class="line"><a id="l01635" name="l01635"></a><span class="lineno"> 1635</span>           <span class="comment">/* (Linux) OS thread name will truncate .nickname() to 15-5=10 chars here; high chance that&#39;ll include</span></div>
<div class="line"><a id="l01636" name="l01636"></a><span class="lineno"> 1636</span><span class="comment">            * something decently useful; probably not everything though; depends on nickname.  It&#39;s a decent attempt. */</span></div>
<div class="line"><a id="l01637" name="l01637"></a><span class="lineno"> 1637</span>           flow::util::ostream_op_string(<span class="stringliteral">&quot;StCh-&quot;</span>, channel.nickname())),</div>
<div class="line"><a id="l01638" name="l01638"></a><span class="lineno"> 1638</span>  <span class="comment">// Create our sync_io core (the thing without threads).</span></div>
<div class="line"><a id="l01639" name="l01639"></a><span class="lineno"> 1639</span>  m_sync_io(get_logger(), std::move(channel), std::forward&lt;Ctor_args&gt;(ctor_args)...)</div>
<div class="line"><a id="l01640" name="l01640"></a><span class="lineno"> 1640</span>{</div>
<div class="line"><a id="l01641" name="l01641"></a><span class="lineno"> 1641</span>  <span class="keyword">using </span><a class="code hl_class" href="classipc_1_1util_1_1sync__io_1_1Asio__waitable__native__handle.html">util::sync_io::Asio_waitable_native_handle</a>;</div>
<div class="line"><a id="l01642" name="l01642"></a><span class="lineno"> 1642</span>  <span class="keyword">using </span><a class="code hl_typedef" href="namespaceipc_1_1util_1_1sync__io.html#ac6973c71fc70c6d867b0f2255c642532">util::sync_io::Task_ptr</a>;</div>
<div class="line"><a id="l01643" name="l01643"></a><span class="lineno"> 1643</span>  <span class="keyword">using </span>flow::async::reset_this_thread_pinning;</div>
<div class="line"><a id="l01644" name="l01644"></a><span class="lineno"> 1644</span> </div>
<div class="line"><a id="l01645" name="l01645"></a><span class="lineno"> 1645</span>  FLOW_LOG_INFO(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Created from struc::sync_io::Channel core which was &quot;</span></div>
<div class="line"><a id="l01646" name="l01646"></a><span class="lineno"> 1646</span>                <span class="stringliteral">&quot;just created (details above).  Async-worker thread shall start.&quot;</span>);</div>
<div class="line"><a id="l01647" name="l01647"></a><span class="lineno"> 1647</span> </div>
<div class="line"><a id="l01648" name="l01648"></a><span class="lineno"> 1648</span>  <span class="comment">// We do need this before our start(), in case they call async_end_sending() without start() (which is allowed).</span></div>
<div class="line"><a id="l01649" name="l01649"></a><span class="lineno"> 1649</span>  <a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#a2184077da7828589d20d7f92a31a6394">m_worker</a>.start(reset_this_thread_pinning); <span class="comment">// Don&#39;t inherit any strange core-affinity!  Worker must float free.</span></div>
<div class="line"><a id="l01650" name="l01650"></a><span class="lineno"> 1650</span> </div>
<div class="line"><a id="l01651" name="l01651"></a><span class="lineno"> 1651</span>  <span class="comment">// We&#39;re using a boost.asio event loop, so we need to base the async-waited-on handles on our Task_engine.</span></div>
<div class="line"><a id="l01652" name="l01652"></a><span class="lineno"> 1652</span><span class="preprocessor">#ifndef NDEBUG</span></div>
<div class="line"><a id="l01653" name="l01653"></a><span class="lineno"> 1653</span>  <span class="keywordtype">bool</span> ok =</div>
<div class="line"><a id="l01654" name="l01654"></a><span class="lineno"> 1654</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l01655" name="l01655"></a><span class="lineno"> 1655</span>  <a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#aefee55a9e754a63ce52766d6c65df92c">m_sync_io</a>.<a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a543aa806ec21b8550f9f440e59767d52">replace_event_wait_handles</a>([<span class="keyword">this</span>]() -&gt; Asio_waitable_native_handle</div>
<div class="line"><a id="l01656" name="l01656"></a><span class="lineno"> 1656</span>                                         { <span class="keywordflow">return</span> Asio_waitable_native_handle(*(<a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#a2184077da7828589d20d7f92a31a6394">m_worker</a>.task_engine())); });</div>
<div class="line"><a id="l01657" name="l01657"></a><span class="lineno"> 1657</span>  assert(ok);</div>
<div class="line"><a id="l01658" name="l01658"></a><span class="lineno"> 1658</span> </div>
<div class="line"><a id="l01659" name="l01659"></a><span class="lineno"> 1659</span><span class="preprocessor">#ifndef NDEBUG</span></div>
<div class="line"><a id="l01660" name="l01660"></a><span class="lineno"> 1660</span>  ok =</div>
<div class="line"><a id="l01661" name="l01661"></a><span class="lineno"> 1661</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l01662" name="l01662"></a><span class="lineno"> 1662</span>  <a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#aefee55a9e754a63ce52766d6c65df92c">m_sync_io</a>.<a class="code hl_function" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a6e4f8c4207fcf678b4cfc785707d3dce">start_ops</a>([<span class="keyword">this</span>](Asio_waitable_native_handle* hndl_of_interest,</div>
<div class="line"><a id="l01663" name="l01663"></a><span class="lineno"> 1663</span>                             <span class="keywordtype">bool</span> ev_of_interest_snd_else_rcv,</div>
<div class="line"><a id="l01664" name="l01664"></a><span class="lineno"> 1664</span>                             <a class="code hl_typedef" href="namespaceipc_1_1util_1_1sync__io.html#ac6973c71fc70c6d867b0f2255c642532">Task_ptr</a>&amp;&amp; on_active_ev_func)</div>
<div class="line"><a id="l01665" name="l01665"></a><span class="lineno"> 1665</span>  {</div>
<div class="line"><a id="l01666" name="l01666"></a><span class="lineno"> 1666</span>    <span class="comment">// We are in thread U or thread W.  m_mutex is locked.</span></div>
<div class="line"><a id="l01667" name="l01667"></a><span class="lineno"> 1667</span> </div>
<div class="line"><a id="l01668" name="l01668"></a><span class="lineno"> 1668</span>    FLOW_LOG_TRACE(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Sync-IO event-wait request: &quot;</span></div>
<div class="line"><a id="l01669" name="l01669"></a><span class="lineno"> 1669</span>                   <span class="stringliteral">&quot;descriptor [&quot;</span> &lt;&lt; <a class="code hl_typedef" href="namespaceipc_1_1transport.html#a7ee4551983d9df16ec16a3139bac50e8">Native_handle</a>(hndl_of_interest-&gt;native_handle()) &lt;&lt; <span class="stringliteral">&quot;], &quot;</span></div>
<div class="line"><a id="l01670" name="l01670"></a><span class="lineno"> 1670</span>                   <span class="stringliteral">&quot;writable-else-readable [&quot;</span> &lt;&lt; ev_of_interest_snd_else_rcv &lt;&lt; <span class="stringliteral">&quot;].&quot;</span>);</div>
<div class="line"><a id="l01671" name="l01671"></a><span class="lineno"> 1671</span> </div>
<div class="line"><a id="l01672" name="l01672"></a><span class="lineno"> 1672</span>    <span class="comment">// They want this async_wait().  Oblige.</span></div>
<div class="line"><a id="l01673" name="l01673"></a><span class="lineno"> 1673</span>    assert(hndl_of_interest);</div>
<div class="line"><a id="l01674" name="l01674"></a><span class="lineno"> 1674</span>    hndl_of_interest-&gt;async_wait(ev_of_interest_snd_else_rcv</div>
<div class="line"><a id="l01675" name="l01675"></a><span class="lineno"> 1675</span>                                   ? Asio_waitable_native_handle::Base::wait_write</div>
<div class="line"><a id="l01676" name="l01676"></a><span class="lineno"> 1676</span>                                   : Asio_waitable_native_handle::Base::wait_read,</div>
<div class="line"><a id="l01677" name="l01677"></a><span class="lineno"> 1677</span>                                 [<span class="keyword">this</span>, on_active_ev_func = std::move(on_active_ev_func)]</div>
<div class="line"><a id="l01678" name="l01678"></a><span class="lineno"> 1678</span>                                   (<span class="keyword">const</span> <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a>&amp; err_code)</div>
<div class="line"><a id="l01679" name="l01679"></a><span class="lineno"> 1679</span>    {</div>
<div class="line"><a id="l01680" name="l01680"></a><span class="lineno"> 1680</span>      <span class="comment">// We are in thread W.  Nothing is locked.</span></div>
<div class="line"><a id="l01681" name="l01681"></a><span class="lineno"> 1681</span> </div>
<div class="line"><a id="l01682" name="l01682"></a><span class="lineno"> 1682</span>      <span class="keywordflow">if</span> (err_code == boost::asio::error::operation_aborted)</div>
<div class="line"><a id="l01683" name="l01683"></a><span class="lineno"> 1683</span>      {</div>
<div class="line"><a id="l01684" name="l01684"></a><span class="lineno"> 1684</span>        <span class="keywordflow">return</span>; <span class="comment">// Stuff is shutting down.  GTFO.</span></div>
<div class="line"><a id="l01685" name="l01685"></a><span class="lineno"> 1685</span>      }</div>
<div class="line"><a id="l01686" name="l01686"></a><span class="lineno"> 1686</span>      <span class="comment">// else</span></div>
<div class="line"><a id="l01687" name="l01687"></a><span class="lineno"> 1687</span> </div>
<div class="line"><a id="l01688" name="l01688"></a><span class="lineno"> 1688</span>      <span class="comment">// They want to know about completed async_wait().  Oblige.</span></div>
<div class="line"><a id="l01689" name="l01689"></a><span class="lineno"> 1689</span> </div>
<div class="line"><a id="l01690" name="l01690"></a><span class="lineno"> 1690</span>      <span class="comment">// Protect m_sync_io, m_sync_op_state, m_snd_end_sending_on_done_func_or_empty (at least).</span></div>
<div class="line"><a id="l01691" name="l01691"></a><span class="lineno"> 1691</span>      <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(<a class="code hl_variable" href="classipc_1_1transport_1_1struc_1_1Channel.html#a01c90903e715ebcf64d8b5ea0d114bc0">m_mutex</a>);</div>
<div class="line"><a id="l01692" name="l01692"></a><span class="lineno"> 1692</span> </div>
<div class="line"><a id="l01693" name="l01693"></a><span class="lineno"> 1693</span>      <span class="comment">/* Inform m_sync_io of the event.  This can synchronously invoke one of many handlers we have potentially</span></div>
<div class="line"><a id="l01694" name="l01694"></a><span class="lineno"> 1694</span><span class="comment">       * registered via m_sync_io API.  E.g., there could be an incoming structured message user is expecting.  Or</span></div>
<div class="line"><a id="l01695" name="l01695"></a><span class="lineno"> 1695</span><span class="comment">       * it could be the error handler set up in our start(). */</span></div>
<div class="line"><a id="l01696" name="l01696"></a><span class="lineno"> 1696</span> </div>
<div class="line"><a id="l01697" name="l01697"></a><span class="lineno"> 1697</span>      (*on_active_ev_func)();</div>
<div class="line"><a id="l01698" name="l01698"></a><span class="lineno"> 1698</span>      <span class="comment">// (That would have logged sufficiently inside m_sync_io; let&#39;s not spam further.)</span></div>
<div class="line"><a id="l01699" name="l01699"></a><span class="lineno"> 1699</span>    }); <span class="comment">// hndl_of_interest-&gt;async_wait()</span></div>
<div class="line"><a id="l01700" name="l01700"></a><span class="lineno"> 1700</span>  });</div>
<div class="line"><a id="l01701" name="l01701"></a><span class="lineno"> 1701</span>  assert(ok &amp;&amp; <span class="stringliteral">&quot;Bug?  If replace_event_wait_handles() worked, start_ops() should too.&quot;</span>);</div>
<div class="line"><a id="l01702" name="l01702"></a><span class="lineno"> 1702</span>} <span class="comment">// Channel::Channel()</span></div>
<div class="line"><a id="l01703" name="l01703"></a><span class="lineno"> 1703</span> </div>
<div class="line"><a id="l01704" name="l01704"></a><span class="lineno"> 1704</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l01705" name="l01705"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#abf9f4ae00258efb7a5d868a087658ffe"> 1705</a></span>CLASS_STRUCTURED_CHANNEL::~Channel()</div>
<div class="line"><a id="l01706" name="l01706"></a><span class="lineno"> 1706</span>{</div>
<div class="line"><a id="l01707" name="l01707"></a><span class="lineno"> 1707</span>  <span class="keyword">using </span>flow::async::Single_thread_task_loop;</div>
<div class="line"><a id="l01708" name="l01708"></a><span class="lineno"> 1708</span>  <span class="keyword">using </span>flow::async::reset_thread_pinning;</div>
<div class="line"><a id="l01709" name="l01709"></a><span class="lineno"> 1709</span>  <span class="keyword">using </span>flow::util::ostream_op_string;</div>
<div class="line"><a id="l01710" name="l01710"></a><span class="lineno"> 1710</span> </div>
<div class="line"><a id="l01711" name="l01711"></a><span class="lineno"> 1711</span>  <span class="comment">// We are in thread U.</span></div>
<div class="line"><a id="l01712" name="l01712"></a><span class="lineno"> 1712</span> </div>
<div class="line"><a id="l01713" name="l01713"></a><span class="lineno"> 1713</span>  FLOW_LOG_INFO(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Shutting down.  &quot;</span></div>
<div class="line"><a id="l01714" name="l01714"></a><span class="lineno"> 1714</span>                <span class="stringliteral">&quot;struc::sync_io::Channel shall free various resources soon.  First as needed: our &quot;</span></div>
<div class="line"><a id="l01715" name="l01715"></a><span class="lineno"> 1715</span>                <span class="stringliteral">&quot;internal async handlers (at most end-sending handler) will be canceled; &quot;</span></div>
<div class="line"><a id="l01716" name="l01716"></a><span class="lineno"> 1716</span>                <span class="stringliteral">&quot;and worker thread will be joined.&quot;</span>);</div>
<div class="line"><a id="l01717" name="l01717"></a><span class="lineno"> 1717</span> </div>
<div class="line"><a id="l01718" name="l01718"></a><span class="lineno"> 1718</span>  <span class="comment">/* This (1) stop()s the Task_engine thus possibly preventing any more handlers from running at all</span></div>
<div class="line"><a id="l01719" name="l01719"></a><span class="lineno"> 1719</span><span class="comment">   * (any handler possibly running now is the last one to run).  To be clear that&#39;s one of these:</span></div>
<div class="line"><a id="l01720" name="l01720"></a><span class="lineno"> 1720</span><span class="comment">   *   - The async_wait() handler from start_ops() (see ctor); if that&#39;s running it&#39;s deep inside a peer object</span></div>
<div class="line"><a id="l01721" name="l01721"></a><span class="lineno"> 1721</span><span class="comment">   *     inside m_sync_io (which just forwards to its Owned_channel m_channel... black box to us but just saying).</span></div>
<div class="line"><a id="l01722" name="l01722"></a><span class="lineno"> 1722</span><span class="comment">   *     So like for example it might updating its internal cached in-messages not yet emitted to user, because</span></div>
<div class="line"><a id="l01723" name="l01723"></a><span class="lineno"> 1723</span><span class="comment">   *     they haven&#39;t expect_msg()ed it yet.</span></div>
<div class="line"><a id="l01724" name="l01724"></a><span class="lineno"> 1724</span><span class="comment">   *   - We&#39;ve post()ed (onto thread W -- this very Task_engine/Single_thread_task_loop) a user handler for</span></div>
<div class="line"><a id="l01725" name="l01725"></a><span class="lineno"> 1725</span><span class="comment">   *     an expect_msg(), or the error handler given to start(), or response to a send()ed request... etc.</span></div>
<div class="line"><a id="l01726" name="l01726"></a><span class="lineno"> 1726</span><span class="comment">   *     So that guy is running right now then.</span></div>
<div class="line"><a id="l01727" name="l01727"></a><span class="lineno"> 1727</span><span class="comment">   *</span></div>
<div class="line"><a id="l01728" name="l01728"></a><span class="lineno"> 1728</span><span class="comment">   * Anyway, this (1) will await for that to finish -- as-if the dtor was invoked just after.  Moving on:</span></div>
<div class="line"><a id="l01729" name="l01729"></a><span class="lineno"> 1729</span><span class="comment">   * (2) at that point Task_engine::run() exits, hence thread W exits; (3) it joins thread W (waits for it to</span></div>
<div class="line"><a id="l01730" name="l01730"></a><span class="lineno"> 1730</span><span class="comment">   * exit); (4) returns.  That&#39;s a lot, but it&#39;s non-blocking. */</span></div>
<div class="line"><a id="l01731" name="l01731"></a><span class="lineno"> 1731</span>  m_worker.stop(); <span class="comment">// Task_engine can be accessed concurrently without locking.</span></div>
<div class="line"><a id="l01732" name="l01732"></a><span class="lineno"> 1732</span>  <span class="comment">// Thread W is (synchronously!) no more.</span></div>
<div class="line"><a id="l01733" name="l01733"></a><span class="lineno"> 1733</span> </div>
<div class="line"><a id="l01734" name="l01734"></a><span class="lineno"> 1734</span>  <span class="comment">/* As we promised in doc header(s), the destruction of *this shall cause any registered completion</span></div>
<div class="line"><a id="l01735" name="l01735"></a><span class="lineno"> 1735</span><span class="comment">   * handlers to be called from some unspecified thread(s) that aren&#39;t thread U, and once</span></div>
<div class="line"><a id="l01736" name="l01736"></a><span class="lineno"> 1736</span><span class="comment">   * they&#39;ve all finished, the dtor returns.  For us there&#39;s only possible such one-off handler:</span></div>
<div class="line"><a id="l01737" name="l01737"></a><span class="lineno"> 1737</span><span class="comment">   * from async_end_sending().  Plus... just...</span></div>
<div class="line"><a id="l01738" name="l01738"></a><span class="lineno"> 1738</span><span class="comment">   *</span></div>
<div class="line"><a id="l01739" name="l01739"></a><span class="lineno"> 1739</span><span class="comment">   * ...See comment in similar spot in Native_socket_stream::~Impl() regarding all that/the following.</span></div>
<div class="line"><a id="l01740" name="l01740"></a><span class="lineno"> 1740</span><span class="comment">   *</span></div>
<div class="line"><a id="l01741" name="l01741"></a><span class="lineno"> 1741</span><span class="comment">   * The 2 tasks, summarized are:</span></div>
<div class="line"><a id="l01742" name="l01742"></a><span class="lineno"> 1742</span><span class="comment">   *   - Task_engine::poll(): Like Native_socket_stream::Impl::~Impl() inline code that does that.</span></div>
<div class="line"><a id="l01743" name="l01743"></a><span class="lineno"> 1743</span><span class="comment">   *   - Fire async_end_sending() un-fired handler if any: Like Async_sender_adapter::~dtor() call that does</span></div>
<div class="line"><a id="l01744" name="l01744"></a><span class="lineno"> 1744</span><span class="comment">   *     that.</span></div>
<div class="line"><a id="l01745" name="l01745"></a><span class="lineno"> 1745</span><span class="comment">   *</span></div>
<div class="line"><a id="l01746" name="l01746"></a><span class="lineno"> 1746</span><span class="comment">   * ### Digression for context ###</span></div>
<div class="line"><a id="l01747" name="l01747"></a><span class="lineno"> 1747</span><span class="comment">   * Non-sync_io transport::Native_socket_stream::Impl uses Async_adapter_sender to adapt a</span></div>
<div class="line"><a id="l01748" name="l01748"></a><span class="lineno"> 1748</span><span class="comment">   * sync_io::Native_socket_stream; so ~Async_adapter_sender() has to give operation-aborted to any</span></div>
<div class="line"><a id="l01749" name="l01749"></a><span class="lineno"> 1749</span><span class="comment">   * one-off async-op handlers that are outstanding; and in that guy that is, just like for us,</span></div>
<div class="line"><a id="l01750" name="l01750"></a><span class="lineno"> 1750</span><span class="comment">   * at worst the F() in async_end_sending(F).  Before that, same as for us, queued-up Task_engine handlers</span></div>
<div class="line"><a id="l01751" name="l01751"></a><span class="lineno"> 1751</span><span class="comment">   * may need to be flushed via Task_engine::poll().</span></div>
<div class="line"><a id="l01752" name="l01752"></a><span class="lineno"> 1752</span><span class="comment">   *</span></div>
<div class="line"><a id="l01753" name="l01753"></a><span class="lineno"> 1753</span><span class="comment">   * We, however, don&#39;t use Mr. transport::Native_socket_stream or transport::Blob_stream_mq_sender/receiver</span></div>
<div class="line"><a id="l01754" name="l01754"></a><span class="lineno"> 1754</span><span class="comment">   * but only their sync_io cores sync_io::*_stream* -- they would starts their own threads, and per our</span></div>
<div class="line"><a id="l01755" name="l01755"></a><span class="lineno"> 1755</span><span class="comment">   * class doc header impl section we don&#39;t want that overhead.  So we maintain thread W ourselves and deal</span></div>
<div class="line"><a id="l01756" name="l01756"></a><span class="lineno"> 1756</span><span class="comment">   * with the sync_io::Native_socket_stream -- and/or sync_io::Blob/Native_handle_sender and/or whatever</span></div>
<div class="line"><a id="l01757" name="l01757"></a><span class="lineno"> 1757</span><span class="comment">   * other `Channel`-supported guys -- via struc::sync_io::Channel m_sync_io (which deals with those</span></div>
<div class="line"><a id="l01758" name="l01758"></a><span class="lineno"> 1758</span><span class="comment">   * sync_io core peer objects via bundling transport::Channel; lots of layers here).</span></div>
<div class="line"><a id="l01759" name="l01759"></a><span class="lineno"> 1759</span><span class="comment">   *</span></div>
<div class="line"><a id="l01760" name="l01760"></a><span class="lineno"> 1760</span><span class="comment">   * My point: As the async-I/O-pattern N_s_s or B_s_mq_sender/receiver each run a thread W and thus each has to</span></div>
<div class="line"><a id="l01761" name="l01761"></a><span class="lineno"> 1761</span><span class="comment">   * take care of invoking un-fired handlers, so similarly must we.  Blob_stream_mq_sender -- same deal.</span></div>
<div class="line"><a id="l01762" name="l01762"></a><span class="lineno"> 1762</span><span class="comment">   * The logic is therefore quite similar. */</span></div>
<div class="line"><a id="l01763" name="l01763"></a><span class="lineno"> 1763</span> </div>
<div class="line"><a id="l01764" name="l01764"></a><span class="lineno"> 1764</span>  FLOW_LOG_INFO(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Continuing shutdown.  Next we will run pending handlers &quot;</span></div>
<div class="line"><a id="l01765" name="l01765"></a><span class="lineno"> 1765</span>                <span class="stringliteral">&quot;from some other thread.  In this user thread we will await those handlers&#39; completion and then &quot;</span></div>
<div class="line"><a id="l01766" name="l01766"></a><span class="lineno"> 1766</span>                <span class="stringliteral">&quot;return.&quot;</span>);</div>
<div class="line"><a id="l01767" name="l01767"></a><span class="lineno"> 1767</span> </div>
<div class="line"><a id="l01768" name="l01768"></a><span class="lineno"> 1768</span>  Single_thread_task_loop one_thread(get_logger(),</div>
<div class="line"><a id="l01769" name="l01769"></a><span class="lineno"> 1769</span>                                     ostream_op_string(<span class="stringliteral">&quot;StChDeinit-&quot;</span>, owned_channel().nickname()));</div>
<div class="line"><a id="l01770" name="l01770"></a><span class="lineno"> 1770</span>  one_thread.start([&amp;]()</div>
<div class="line"><a id="l01771" name="l01771"></a><span class="lineno"> 1771</span>  {</div>
<div class="line"><a id="l01772" name="l01772"></a><span class="lineno"> 1772</span>    reset_thread_pinning(get_logger()); <span class="comment">// Don&#39;t inherit any strange core-affinity.  Float free.</span></div>
<div class="line"><a id="l01773" name="l01773"></a><span class="lineno"> 1773</span> </div>
<div class="line"><a id="l01774" name="l01774"></a><span class="lineno"> 1774</span>    FLOW_LOG_INFO(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: &quot;</span></div>
<div class="line"><a id="l01775" name="l01775"></a><span class="lineno"> 1775</span>                  <span class="stringliteral">&quot;In transient finisher thread: Shall run all pending internal handlers (typically none).&quot;</span>);</div>
<div class="line"><a id="l01776" name="l01776"></a><span class="lineno"> 1776</span> </div>
<div class="line"><a id="l01777" name="l01777"></a><span class="lineno"> 1777</span>    <span class="keyword">const</span> <span class="keyword">auto</span> task_engine = m_worker.task_engine();</div>
<div class="line"><a id="l01778" name="l01778"></a><span class="lineno"> 1778</span>    task_engine-&gt;restart();</div>
<div class="line"><a id="l01779" name="l01779"></a><span class="lineno"> 1779</span>    <span class="keyword">const</span> <span class="keyword">auto</span> count = task_engine-&gt;poll();</div>
<div class="line"><a id="l01780" name="l01780"></a><span class="lineno"> 1780</span>    <span class="keywordflow">if</span> (count != 0)</div>
<div class="line"><a id="l01781" name="l01781"></a><span class="lineno"> 1781</span>    {</div>
<div class="line"><a id="l01782" name="l01782"></a><span class="lineno"> 1782</span>      FLOW_LOG_INFO(<span class="stringliteral">&quot;Blob_stream_mq_sender [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: &quot;</span></div>
<div class="line"><a id="l01783" name="l01783"></a><span class="lineno"> 1783</span>                    <span class="stringliteral">&quot;In transient finisher thread: Ran [&quot;</span> &lt;&lt; count &lt;&lt; <span class="stringliteral">&quot;] internal handlers after all.&quot;</span>);</div>
<div class="line"><a id="l01784" name="l01784"></a><span class="lineno"> 1784</span>    }</div>
<div class="line"><a id="l01785" name="l01785"></a><span class="lineno"> 1785</span>    task_engine-&gt;stop();</div>
<div class="line"><a id="l01786" name="l01786"></a><span class="lineno"> 1786</span> </div>
<div class="line"><a id="l01787" name="l01787"></a><span class="lineno"> 1787</span>    <span class="keywordflow">if</span> (!m_snd_end_sending_on_done_func_or_empty.empty())</div>
<div class="line"><a id="l01788" name="l01788"></a><span class="lineno"> 1788</span>    {</div>
<div class="line"><a id="l01789" name="l01789"></a><span class="lineno"> 1789</span>      FLOW_LOG_INFO(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: In transient snd-finisher thread: &quot;</span></div>
<div class="line"><a id="l01790" name="l01790"></a><span class="lineno"> 1790</span>                    <span class="stringliteral">&quot;Shall run pending graceful-sends-close completion handler.&quot;</span>);</div>
<div class="line"><a id="l01791" name="l01791"></a><span class="lineno"> 1791</span>      m_snd_end_sending_on_done_func_or_empty(<a class="code hl_enumvalue" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297afe29343445a7bf167cc186a44bd2c6ed">transport::error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER</a>);</div>
<div class="line"><a id="l01792" name="l01792"></a><span class="lineno"> 1792</span>    } <span class="comment">// if (!m_snd_end_sending_on_done_func_or_empty.empty())</span></div>
<div class="line"><a id="l01793" name="l01793"></a><span class="lineno"> 1793</span> </div>
<div class="line"><a id="l01794" name="l01794"></a><span class="lineno"> 1794</span>    FLOW_LOG_INFO(<span class="stringliteral">&quot;Transient finisher exiting.&quot;</span>);</div>
<div class="line"><a id="l01795" name="l01795"></a><span class="lineno"> 1795</span>  });</div>
<div class="line"><a id="l01796" name="l01796"></a><span class="lineno"> 1796</span>  <span class="comment">// Here thread exits/joins synchronously.</span></div>
<div class="line"><a id="l01797" name="l01797"></a><span class="lineno"> 1797</span>} <span class="comment">// Channel::~Channel()</span></div>
<div class="line"><a id="l01798" name="l01798"></a><span class="lineno"> 1798</span> </div>
<div class="line"><a id="l01799" name="l01799"></a><span class="lineno"> 1799</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l01800" name="l01800"></a><span class="lineno"> 1800</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Task_err&gt;</div>
<div class="line"><a id="l01801" name="l01801"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ab08057edd9832d94ea0e18a17c42200a"> 1801</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::async_end_sending(Task_err&amp;&amp; on_done_func)</div>
<div class="line"><a id="l01802" name="l01802"></a><span class="lineno"> 1802</span>{</div>
<div class="line"><a id="l01803" name="l01803"></a><span class="lineno"> 1803</span>  <span class="comment">/* We are in thread U, or thread W (executing from a handler, possibly concurrently with other APIs).</span></div>
<div class="line"><a id="l01804" name="l01804"></a><span class="lineno"> 1804</span><span class="comment">   * Nothing is locked regardless (see discussion in expect_msg() where we set up that handler). */</span></div>
<div class="line"><a id="l01805" name="l01805"></a><span class="lineno"> 1805</span> </div>
<div class="line"><a id="l01806" name="l01806"></a><span class="lineno"> 1806</span>  FLOW_LOG_TRACE(<span class="stringliteral">&quot;Structured channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: async_end_sending(F) invoked.&quot;</span>);</div>
<div class="line"><a id="l01807" name="l01807"></a><span class="lineno"> 1807</span> </div>
<div class="line"><a id="l01808" name="l01808"></a><span class="lineno"> 1808</span>  <span class="comment">// Reminder: we must protect against concurrent calls from user threads U1, U2, ...; and against access from W.</span></div>
<div class="line"><a id="l01809" name="l01809"></a><span class="lineno"> 1809</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l01810" name="l01810"></a><span class="lineno"> 1810</span> </div>
<div class="line"><a id="l01811" name="l01811"></a><span class="lineno"> 1811</span>  <span class="keywordflow">if</span> (!m_snd_end_sending_on_done_func_or_empty.empty())</div>
<div class="line"><a id="l01812" name="l01812"></a><span class="lineno"> 1812</span>  {</div>
<div class="line"><a id="l01813" name="l01813"></a><span class="lineno"> 1813</span>    FLOW_LOG_WARNING(<span class="stringliteral">&quot;Structured channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: async_end_sending(F) invoked; but we have a saved &quot;</span></div>
<div class="line"><a id="l01814" name="l01814"></a><span class="lineno"> 1814</span>                     <span class="stringliteral">&quot;completion handler -- which has not yet fired -- for it already, so it must be a dupe-call.  &quot;</span></div>
<div class="line"><a id="l01815" name="l01815"></a><span class="lineno"> 1815</span>                     <span class="stringliteral">&quot;Ignoring.&quot;</span>);</div>
<div class="line"><a id="l01816" name="l01816"></a><span class="lineno"> 1816</span>    <span class="keywordflow">return</span> <span class="keyword">false</span>;</div>
<div class="line"><a id="l01817" name="l01817"></a><span class="lineno"> 1817</span>  }</div>
<div class="line"><a id="l01818" name="l01818"></a><span class="lineno"> 1818</span>  <span class="comment">/* else: It might also be .empty() and still be a dupe call (if it has fired already -- then they called us again).</span></div>
<div class="line"><a id="l01819" name="l01819"></a><span class="lineno"> 1819</span><span class="comment">   *       m_sync_io.async_end_sending() will catch that fine.  For now though: */</span></div>
<div class="line"><a id="l01820" name="l01820"></a><span class="lineno"> 1820</span> </div>
<div class="line"><a id="l01821" name="l01821"></a><span class="lineno"> 1821</span>  <span class="comment">/* Save it (instead of capturing it in lambda) in case dtor runs before async-end-sending completes;</span></div>
<div class="line"><a id="l01822" name="l01822"></a><span class="lineno"> 1822</span><span class="comment">   * it would then invoke it with operation-aborted code. */</span></div>
<div class="line"><a id="l01823" name="l01823"></a><span class="lineno"> 1823</span>  m_snd_end_sending_on_done_func_or_empty = std::move(on_done_func);</div>
<div class="line"><a id="l01824" name="l01824"></a><span class="lineno"> 1824</span> </div>
<div class="line"><a id="l01825" name="l01825"></a><span class="lineno"> 1825</span>  <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> sync_err_code;</div>
<div class="line"><a id="l01826" name="l01826"></a><span class="lineno"> 1826</span>  <span class="keyword">const</span> <span class="keywordtype">bool</span> ok = m_sync_io.async_end_sending(&amp;sync_err_code,</div>
<div class="line"><a id="l01827" name="l01827"></a><span class="lineno"> 1827</span>                                              [<span class="keyword">this</span>](<span class="keyword">const</span> <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a>&amp; err_code) <span class="keyword">mutable</span></div>
<div class="line"><a id="l01828" name="l01828"></a><span class="lineno"> 1828</span>  {</div>
<div class="line"><a id="l01829" name="l01829"></a><span class="lineno"> 1829</span>    <span class="comment">/* We are in thread W (async_end_sending() specifically promises to *not* invoke on_done_func(), or</span></div>
<div class="line"><a id="l01830" name="l01830"></a><span class="lineno"> 1830</span><span class="comment">     * remember it in any way, if the async-end-sending is synchronously successful -- which it will be most of</span></div>
<div class="line"><a id="l01831" name="l01831"></a><span class="lineno"> 1831</span><span class="comment">     * the time (only not so if an out-peer object is currently in would-block)).  In this case, though,</span></div>
<div class="line"><a id="l01832" name="l01832"></a><span class="lineno"> 1832</span><span class="comment">     * there was would-block, so we are being invoked async-style.</span></div>
<div class="line"><a id="l01833" name="l01833"></a><span class="lineno"> 1833</span><span class="comment">     *</span></div>
<div class="line"><a id="l01834" name="l01834"></a><span class="lineno"> 1834</span><span class="comment">     * m_mutex is locked!</span></div>
<div class="line"><a id="l01835" name="l01835"></a><span class="lineno"> 1835</span><span class="comment">     *</span></div>
<div class="line"><a id="l01836" name="l01836"></a><span class="lineno"> 1836</span><span class="comment">     * Should we post()?  Yes, for the same reason as in expect_msg() and others (see discussion in that method). */</span></div>
<div class="line"><a id="l01837" name="l01837"></a><span class="lineno"> 1837</span>    m_worker.post([<span class="keyword">this</span>, err_code]() <span class="keyword">mutable</span></div>
<div class="line"><a id="l01838" name="l01838"></a><span class="lineno"> 1838</span>    {</div>
<div class="line"><a id="l01839" name="l01839"></a><span class="lineno"> 1839</span>      <span class="comment">// We are in thread W.  Nothing is locked.</span></div>
<div class="line"><a id="l01840" name="l01840"></a><span class="lineno"> 1840</span> </div>
<div class="line"><a id="l01841" name="l01841"></a><span class="lineno"> 1841</span>      <span class="keyword">decltype</span>(m_snd_end_sending_on_done_func_or_empty) on_done_func;</div>
<div class="line"><a id="l01842" name="l01842"></a><span class="lineno"> 1842</span>      {</div>
<div class="line"><a id="l01843" name="l01843"></a><span class="lineno"> 1843</span>        <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex); <span class="comment">// Accessing m_snd_end_sending_on_done_func_or_empty.</span></div>
<div class="line"><a id="l01844" name="l01844"></a><span class="lineno"> 1844</span> </div>
<div class="line"><a id="l01845" name="l01845"></a><span class="lineno"> 1845</span>        assert((!m_snd_end_sending_on_done_func_or_empty.empty()) &amp;&amp; <span class="stringliteral">&quot;Only we or dtor can clear this.  Bug?&quot;</span>);</div>
<div class="line"><a id="l01846" name="l01846"></a><span class="lineno"> 1846</span> </div>
<div class="line"><a id="l01847" name="l01847"></a><span class="lineno"> 1847</span>        on_done_func = std::move(m_snd_end_sending_on_done_func_or_empty);</div>
<div class="line"><a id="l01848" name="l01848"></a><span class="lineno"> 1848</span>        m_snd_end_sending_on_done_func_or_empty.clear(); <span class="comment">// (Just in case move() didn&#39;t do it.)</span></div>
<div class="line"><a id="l01849" name="l01849"></a><span class="lineno"> 1849</span> </div>
<div class="line"><a id="l01850" name="l01850"></a><span class="lineno"> 1850</span>        <span class="comment">// Now dtor won&#39;t call it with operation-aborted.</span></div>
<div class="line"><a id="l01851" name="l01851"></a><span class="lineno"> 1851</span> </div>
<div class="line"><a id="l01852" name="l01852"></a><span class="lineno"> 1852</span>        <span class="comment">/* Unlock before invoking handler!  They can call any number of mutex-locking stuff: expect_msg(),</span></div>
<div class="line"><a id="l01853" name="l01853"></a><span class="lineno"> 1853</span><span class="comment">         * even async_end_sending() again, if they&#39;re weird people who like to do odd things. */</span></div>
<div class="line"><a id="l01854" name="l01854"></a><span class="lineno"> 1854</span>      } <span class="comment">// Lock_guard lock(m_mutex);</span></div>
<div class="line"><a id="l01855" name="l01855"></a><span class="lineno"> 1855</span> </div>
<div class="line"><a id="l01856" name="l01856"></a><span class="lineno"> 1856</span>      <span class="comment">// This should be rare, so (another) INFO message seems okay.</span></div>
<div class="line"><a id="l01857" name="l01857"></a><span class="lineno"> 1857</span>      FLOW_LOG_INFO(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Now executing async-end-sending completion handler: &quot;</span></div>
<div class="line"><a id="l01858" name="l01858"></a><span class="lineno"> 1858</span>                    <span class="stringliteral">&quot;async path.&quot;</span>);</div>
<div class="line"><a id="l01859" name="l01859"></a><span class="lineno"> 1859</span>      on_done_func(err_code);</div>
<div class="line"><a id="l01860" name="l01860"></a><span class="lineno"> 1860</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;Handler completed.&quot;</span>);</div>
<div class="line"><a id="l01861" name="l01861"></a><span class="lineno"> 1861</span>    });</div>
<div class="line"><a id="l01862" name="l01862"></a><span class="lineno"> 1862</span>  }); <span class="comment">// ok = m_sync_io.async_end_sending() (async handler path)</span></div>
<div class="line"><a id="l01863" name="l01863"></a><span class="lineno"> 1863</span> </div>
<div class="line"><a id="l01864" name="l01864"></a><span class="lineno"> 1864</span>  <span class="keywordflow">if</span> (!ok)</div>
<div class="line"><a id="l01865" name="l01865"></a><span class="lineno"> 1865</span>  {</div>
<div class="line"><a id="l01866" name="l01866"></a><span class="lineno"> 1866</span>    <span class="comment">// False start (dupe call).  It logged enough.</span></div>
<div class="line"><a id="l01867" name="l01867"></a><span class="lineno"> 1867</span>    m_snd_end_sending_on_done_func_or_empty.clear();</div>
<div class="line"><a id="l01868" name="l01868"></a><span class="lineno"> 1868</span>    <span class="keywordflow">return</span> <span class="keyword">false</span>;</div>
<div class="line"><a id="l01869" name="l01869"></a><span class="lineno"> 1869</span>  }</div>
<div class="line"><a id="l01870" name="l01870"></a><span class="lineno"> 1870</span>  <span class="comment">// else: It either finished synchronously; or it will finish asynchronously.</span></div>
<div class="line"><a id="l01871" name="l01871"></a><span class="lineno"> 1871</span> </div>
<div class="line"><a id="l01872" name="l01872"></a><span class="lineno"> 1872</span>  <span class="keywordflow">if</span> (sync_err_code == <a class="code hl_enumvalue" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297aa667487757f9d6300f6888bac40bcc24">transport::error::Code::S_SYNC_IO_WOULD_BLOCK</a>) <span class="comment">// It TRACE-logged enough about that.</span></div>
<div class="line"><a id="l01873" name="l01873"></a><span class="lineno"> 1873</span>  {</div>
<div class="line"><a id="l01874" name="l01874"></a><span class="lineno"> 1874</span>    <span class="comment">// Async-wait needed before we can complete.  Live to fight another day.</span></div>
<div class="line"><a id="l01875" name="l01875"></a><span class="lineno"> 1875</span>    <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
<div class="line"><a id="l01876" name="l01876"></a><span class="lineno"> 1876</span>  }</div>
<div class="line"><a id="l01877" name="l01877"></a><span class="lineno"> 1877</span>  <span class="comment">// else</span></div>
<div class="line"><a id="l01878" name="l01878"></a><span class="lineno"> 1878</span> </div>
<div class="line"><a id="l01879" name="l01879"></a><span class="lineno"> 1879</span>  <span class="comment">// We are in thread U, possibly (probably).  Never fire handlers except from thread W.</span></div>
<div class="line"><a id="l01880" name="l01880"></a><span class="lineno"> 1880</span>  m_worker.post([<span class="keyword">this</span>, sync_err_code]()</div>
<div class="line"><a id="l01881" name="l01881"></a><span class="lineno"> 1881</span>  {</div>
<div class="line"><a id="l01882" name="l01882"></a><span class="lineno"> 1882</span>    <span class="comment">// We are in thread W.  Nothing is locked.  Similar to above; keeping comments light.  @todo Bit of code reuse.</span></div>
<div class="line"><a id="l01883" name="l01883"></a><span class="lineno"> 1883</span> </div>
<div class="line"><a id="l01884" name="l01884"></a><span class="lineno"> 1884</span>    <span class="keyword">decltype</span>(m_snd_end_sending_on_done_func_or_empty) on_done_func;</div>
<div class="line"><a id="l01885" name="l01885"></a><span class="lineno"> 1885</span>    {</div>
<div class="line"><a id="l01886" name="l01886"></a><span class="lineno"> 1886</span>      <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex); <span class="comment">// Accessing m_snd_end_sending_on_done_func_or_empty.</span></div>
<div class="line"><a id="l01887" name="l01887"></a><span class="lineno"> 1887</span>      assert((!m_snd_end_sending_on_done_func_or_empty.empty()) &amp;&amp; <span class="stringliteral">&quot;Only we or dtor can clear this.  Bug?&quot;</span>);</div>
<div class="line"><a id="l01888" name="l01888"></a><span class="lineno"> 1888</span> </div>
<div class="line"><a id="l01889" name="l01889"></a><span class="lineno"> 1889</span>      on_done_func = std::move(m_snd_end_sending_on_done_func_or_empty);</div>
<div class="line"><a id="l01890" name="l01890"></a><span class="lineno"> 1890</span>      m_snd_end_sending_on_done_func_or_empty.clear(); <span class="comment">// (Just in case move() didn&#39;t do it.)</span></div>
<div class="line"><a id="l01891" name="l01891"></a><span class="lineno"> 1891</span>    }</div>
<div class="line"><a id="l01892" name="l01892"></a><span class="lineno"> 1892</span>    FLOW_LOG_TRACE(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Now executing async-end-sending completion handler: &quot;</span></div>
<div class="line"><a id="l01893" name="l01893"></a><span class="lineno"> 1893</span>                   <span class="stringliteral">&quot;sync path.&quot;</span>);</div>
<div class="line"><a id="l01894" name="l01894"></a><span class="lineno"> 1894</span>    on_done_func(sync_err_code);</div>
<div class="line"><a id="l01895" name="l01895"></a><span class="lineno"> 1895</span>    FLOW_LOG_TRACE(<span class="stringliteral">&quot;Handler completed.&quot;</span>);</div>
<div class="line"><a id="l01896" name="l01896"></a><span class="lineno"> 1896</span>  });</div>
<div class="line"><a id="l01897" name="l01897"></a><span class="lineno"> 1897</span> </div>
<div class="line"><a id="l01898" name="l01898"></a><span class="lineno"> 1898</span>  <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
<div class="line"><a id="l01899" name="l01899"></a><span class="lineno"> 1899</span>} <span class="comment">// Channel::async_end_sending()</span></div>
<div class="line"><a id="l01900" name="l01900"></a><span class="lineno"> 1900</span> </div>
<div class="line"><a id="l01901" name="l01901"></a><span class="lineno"> 1901</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l01902" name="l01902"></a><span class="lineno"> 1902</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Task_err&gt;</div>
<div class="line"><a id="l01903" name="l01903"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a33b4785c212ad88d8322fcc2f4369351"> 1903</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::start(Task_err&amp;&amp; on_err_func)</div>
<div class="line"><a id="l01904" name="l01904"></a><span class="lineno"> 1904</span>{</div>
<div class="line"><a id="l01905" name="l01905"></a><span class="lineno"> 1905</span>  <span class="keyword">using </span>flow::util::Blob;</div>
<div class="line"><a id="l01906" name="l01906"></a><span class="lineno"> 1906</span>  <span class="keyword">using </span>boost::movelib::make_unique;</div>
<div class="line"><a id="l01907" name="l01907"></a><span class="lineno"> 1907</span>  <span class="keyword">using </span>std::holds_alternative;</div>
<div class="line"><a id="l01908" name="l01908"></a><span class="lineno"> 1908</span>  <span class="keyword">using </span>std::get;</div>
<div class="line"><a id="l01909" name="l01909"></a><span class="lineno"> 1909</span>  <span class="keyword">using </span>std::monostate;</div>
<div class="line"><a id="l01910" name="l01910"></a><span class="lineno"> 1910</span> </div>
<div class="line"><a id="l01911" name="l01911"></a><span class="lineno"> 1911</span>  <span class="comment">// We are in thread U.  Nothing is locked.</span></div>
<div class="line"><a id="l01912" name="l01912"></a><span class="lineno"> 1912</span> </div>
<div class="line"><a id="l01913" name="l01913"></a><span class="lineno"> 1913</span>  <span class="comment">/* Reminder: we must protect against concurrent calls from user threads U1, U2, ... (and against access from W</span></div>
<div class="line"><a id="l01914" name="l01914"></a><span class="lineno"> 1914</span><span class="comment">   * though that could not happen before start() -- us). */</span></div>
<div class="line"><a id="l01915" name="l01915"></a><span class="lineno"> 1915</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l01916" name="l01916"></a><span class="lineno"> 1916</span> </div>
<div class="line"><a id="l01917" name="l01917"></a><span class="lineno"> 1917</span>  <span class="keywordflow">return</span> m_sync_io.start_and_poll([<span class="keyword">this</span>, on_err_func = std::move(on_err_func)]</div>
<div class="line"><a id="l01918" name="l01918"></a><span class="lineno"> 1918</span>                                    (<span class="keyword">const</span> <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a>&amp; err_code) <span class="keyword">mutable</span></div>
<div class="line"><a id="l01919" name="l01919"></a><span class="lineno"> 1919</span>  {</div>
<div class="line"><a id="l01920" name="l01920"></a><span class="lineno"> 1920</span>    <span class="comment">/* Though somewhat unlikely (but definitely possible -- there could be an error on the socket/whatever) --</span></div>
<div class="line"><a id="l01921" name="l01921"></a><span class="lineno"> 1921</span><span class="comment">     * start_and_poll() contract says any relevant handler -- including on_err_func() -- may fire *synchronously*.</span></div>
<div class="line"><a id="l01922" name="l01922"></a><span class="lineno"> 1922</span><span class="comment">     * This is the only such API of (our) m_sync_io.  We however promise to never do that (must always use thread W).</span></div>
<div class="line"><a id="l01923" name="l01923"></a><span class="lineno"> 1923</span><span class="comment">     * So for that we have to post().</span></div>
<div class="line"><a id="l01924" name="l01924"></a><span class="lineno"> 1924</span><span class="comment">     *</span></div>
<div class="line"><a id="l01925" name="l01925"></a><span class="lineno"> 1925</span><span class="comment">     * Otherwise (if indeed we are already in thread W, executing from inside the async_wait() handler as seen inside</span></div>
<div class="line"><a id="l01926" name="l01926"></a><span class="lineno"> 1926</span><span class="comment">     * ctor&#39;s start_ops() statement, with m_mutex locked even) this adds a small, unnecessary delay -- no big deal</span></div>
<div class="line"><a id="l01927" name="l01927"></a><span class="lineno"> 1927</span><span class="comment">     * generally and definitely no big deal in this situation.  (We could detect whether it fired synchronously and</span></div>
<div class="line"><a id="l01928" name="l01928"></a><span class="lineno"> 1928</span><span class="comment">     * avoid the post() if not; but it&#39;s not worth the effort.) */</span></div>
<div class="line"><a id="l01929" name="l01929"></a><span class="lineno"> 1929</span>    m_worker.post([<span class="keyword">this</span>, err_code, on_err_func = std::move(on_err_func)]() <span class="keyword">mutable</span></div>
<div class="line"><a id="l01930" name="l01930"></a><span class="lineno"> 1930</span>    {</div>
<div class="line"><a id="l01931" name="l01931"></a><span class="lineno"> 1931</span>      <span class="comment">/* We are in thread W.  Nothing is locked!</span></div>
<div class="line"><a id="l01932" name="l01932"></a><span class="lineno"> 1932</span><span class="comment">       *</span></div>
<div class="line"><a id="l01933" name="l01933"></a><span class="lineno"> 1933</span><span class="comment">       * So, if not for a possible sync_request(), we&#39;d literally just do: on_err_func(err_code).  However suppose</span></div>
<div class="line"><a id="l01934" name="l01934"></a><span class="lineno"> 1934</span><span class="comment">       * a sync_request() is currently executing in thread U.  (In the future we could add other sync_*(): E.g.,</span></div>
<div class="line"><a id="l01935" name="l01935"></a><span class="lineno"> 1935</span><span class="comment">       * sync_&lt;wait for a particular message a-la expect_msg()&gt;.)  In that case we must emit the error to the sync_*()</span></div>
<div class="line"><a id="l01936" name="l01936"></a><span class="lineno"> 1936</span><span class="comment">       * waiting for a result instead of the on-error handler.  That is our overall contract in *this: Report a</span></div>
<div class="line"><a id="l01937" name="l01937"></a><span class="lineno"> 1937</span><span class="comment">       * channel-hosing error exactly once (if ever): either through a send() or sync_request(); or through</span></div>
<div class="line"><a id="l01938" name="l01938"></a><span class="lineno"> 1938</span><span class="comment">       * this error reporting handler -- whichever one happens first. */</span></div>
<div class="line"><a id="l01939" name="l01939"></a><span class="lineno"> 1939</span> </div>
<div class="line"><a id="l01940" name="l01940"></a><span class="lineno"> 1940</span>      {</div>
<div class="line"><a id="l01941" name="l01941"></a><span class="lineno"> 1941</span>        <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l01942" name="l01942"></a><span class="lineno"> 1942</span> </div>
<div class="line"><a id="l01943" name="l01943"></a><span class="lineno"> 1943</span>        <span class="comment">/* Check that (obviously) there is a sync-op in progress; but also (carefully) ensure it does not have a result</span></div>
<div class="line"><a id="l01944" name="l01944"></a><span class="lineno"> 1944</span><span class="comment">         * stored already.  To show this is technically possible imagine this scenario: sync_request() is waiting in</span></div>
<div class="line"><a id="l01945" name="l01945"></a><span class="lineno"> 1945</span><span class="comment">         * thread U; the expected response was received in time and thus placed into m_sync_op_state-&gt;m_result_if_any,</span></div>
<div class="line"><a id="l01946" name="l01946"></a><span class="lineno"> 1946</span><span class="comment">         * and promise m_sync_op_state-&gt;m_op_done_signal was tickled to wake up thread U&#39;s future.wait_for();</span></div>
<div class="line"><a id="l01947" name="l01947"></a><span class="lineno"> 1947</span><span class="comment">         * but thread U hasn&#39;t yet woken up and nullified m_sync_op_state.  So now we let that sync_request() return</span></div>
<div class="line"><a id="l01948" name="l01948"></a><span class="lineno"> 1948</span><span class="comment">         * success; we then emit the error asynchronously.  Basically it&#39;s almost as-if the error occurred just after</span></div>
<div class="line"><a id="l01949" name="l01949"></a><span class="lineno"> 1949</span><span class="comment">         * the successful sync_request(). */</span></div>
<div class="line"><a id="l01950" name="l01950"></a><span class="lineno"> 1950</span>        <span class="keywordflow">if</span> (m_sync_op_state)</div>
<div class="line"><a id="l01951" name="l01951"></a><span class="lineno"> 1951</span>        {</div>
<div class="line"><a id="l01952" name="l01952"></a><span class="lineno"> 1952</span>          assert((!holds_alternative&lt;Error_code&gt;(m_sync_op_state-&gt;m_result_if_any))</div>
<div class="line"><a id="l01953" name="l01953"></a><span class="lineno"> 1953</span>                 &amp;&amp; <span class="stringliteral">&quot;Only a previous error-handler would have set that to an Error_code; and m_sync_io shall not &quot;</span></div>
<div class="line"><a id="l01954" name="l01954"></a><span class="lineno"> 1954</span>                    <span class="stringliteral">&quot;emit error more than once.&quot;</span>);</div>
<div class="line"><a id="l01955" name="l01955"></a><span class="lineno"> 1955</span>          <span class="keywordflow">if</span> (holds_alternative&lt;monostate&gt;(m_sync_op_state-&gt;m_result_if_any))</div>
<div class="line"><a id="l01956" name="l01956"></a><span class="lineno"> 1956</span>          {</div>
<div class="line"><a id="l01957" name="l01957"></a><span class="lineno"> 1957</span>            FLOW_LOG_TRACE(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Sync-IO core reported error (details above); &quot;</span></div>
<div class="line"><a id="l01958" name="l01958"></a><span class="lineno"> 1958</span>                           <span class="stringliteral">&quot;this occurred while awaiting sync-op (ID [&quot;</span> &lt;&lt; m_sync_op_state-&gt;m_id &lt;&lt; <span class="stringliteral">&quot;]) completion.  &quot;</span></div>
<div class="line"><a id="l01959" name="l01959"></a><span class="lineno"> 1959</span>                           <span class="stringliteral">&quot;Therefore we emit the error to that guy, loading that result and waking the waiting guy.&quot;</span>);</div>
<div class="line"><a id="l01960" name="l01960"></a><span class="lineno"> 1960</span> </div>
<div class="line"><a id="l01961" name="l01961"></a><span class="lineno"> 1961</span>            m_sync_op_state-&gt;m_result_if_any = err_code;</div>
<div class="line"><a id="l01962" name="l01962"></a><span class="lineno"> 1962</span>            m_sync_op_state-&gt;m_op_done_signal.set_value();</div>
<div class="line"><a id="l01963" name="l01963"></a><span class="lineno"> 1963</span>            <span class="keywordflow">return</span>;</div>
<div class="line"><a id="l01964" name="l01964"></a><span class="lineno"> 1964</span>          }</div>
<div class="line"><a id="l01965" name="l01965"></a><span class="lineno"> 1965</span>          <span class="comment">// else { sync_*() already received a success result; so we let that happen. }</span></div>
<div class="line"><a id="l01966" name="l01966"></a><span class="lineno"> 1966</span>        } <span class="comment">// if (m_sync_op_state)</span></div>
<div class="line"><a id="l01967" name="l01967"></a><span class="lineno"> 1967</span>        <span class="comment">// else if (!m_sync_op_state) { No sync_*() in progress. }</span></div>
<div class="line"><a id="l01968" name="l01968"></a><span class="lineno"> 1968</span>      } <span class="comment">// Lock_guard lock(m_mutex)</span></div>
<div class="line"><a id="l01969" name="l01969"></a><span class="lineno"> 1969</span> </div>
<div class="line"><a id="l01970" name="l01970"></a><span class="lineno"> 1970</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Calling error handler from async-worker thread.&quot;</span>);</div>
<div class="line"><a id="l01971" name="l01971"></a><span class="lineno"> 1971</span>      on_err_func(err_code);</div>
<div class="line"><a id="l01972" name="l01972"></a><span class="lineno"> 1972</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;Handler completed.&quot;</span>);</div>
<div class="line"><a id="l01973" name="l01973"></a><span class="lineno"> 1973</span>    }); <span class="comment">// m_worker.post()</span></div>
<div class="line"><a id="l01974" name="l01974"></a><span class="lineno"> 1974</span>  }); <span class="comment">// m_sync_io.post()</span></div>
<div class="line"><a id="l01975" name="l01975"></a><span class="lineno"> 1975</span>} <span class="comment">// Channel::start()</span></div>
<div class="line"><a id="l01976" name="l01976"></a><span class="lineno"> 1976</span> </div>
<div class="line"><a id="l01977" name="l01977"></a><span class="lineno"> 1977</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l01978" name="l01978"></a><span class="lineno"> 1978</span><span class="keyword">typename</span> <a class="code hl_struct" href="structipc_1_1transport_1_1struc_1_1Heap__fixed__builder_1_1Config.html">Heap_fixed_builder::Config</a> <span class="comment">// Static.</span></div>
<div class="line"><a id="l01979" name="l01979"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a08062e4cc99347e94e9e917b382985ee"> 1979</a></span>  CLASS_STRUCTURED_CHANNEL::heap_fixed_builder_config(<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4a0188052c15cab70d712f41b0e74ba7">Owned_channel</a>&amp; channel)</div>
<div class="line"><a id="l01980" name="l01980"></a><span class="lineno"> 1980</span>{</div>
<div class="line"><a id="l01981" name="l01981"></a><span class="lineno"> 1981</span>  <span class="comment">/* This (and similar below) could have been in sync_io::Channel instead.  Doesn&#39;t really matter.</span></div>
<div class="line"><a id="l01982" name="l01982"></a><span class="lineno"> 1982</span><span class="comment">   * I just figured one place for these special static guys is enough, and if we pick one it should be</span></div>
<div class="line"><a id="l01983" name="l01983"></a><span class="lineno"> 1983</span><span class="comment">   * in the higher namespace most users are likelier to use. */</span></div>
<div class="line"><a id="l01984" name="l01984"></a><span class="lineno"> 1984</span> </div>
<div class="line"><a id="l01985" name="l01985"></a><span class="lineno"> 1985</span>  assert(channel.initialized()</div>
<div class="line"><a id="l01986" name="l01986"></a><span class="lineno"> 1986</span>         &amp;&amp; <span class="stringliteral">&quot;Method contract is that the tested `channel` is .initialized().&quot;</span>);</div>
<div class="line"><a id="l01987" name="l01987"></a><span class="lineno"> 1987</span> </div>
<div class="line"><a id="l01988" name="l01988"></a><span class="lineno"> 1988</span>  <span class="comment">/* The assumption is they plan to create a Channel like us, passing `channel` into ctor,</span></div>
<div class="line"><a id="l01989" name="l01989"></a><span class="lineno"> 1989</span><span class="comment">   * with Struct_builder_config being Heap_fixed_builder::Config or similar.  They</span></div>
<div class="line"><a id="l01990" name="l01990"></a><span class="lineno"> 1990</span><span class="comment">   * want a Config they can pass to our ctor.  So we need to know what to pass to its ctor.</span></div>
<div class="line"><a id="l01991" name="l01991"></a><span class="lineno"> 1991</span><span class="comment">   * We have logger_ptr already.  So we need:</span></div>
<div class="line"><a id="l01992" name="l01992"></a><span class="lineno"> 1992</span><span class="comment">   *   - segment_sz: Max size of each segment in the serialization of the structured message itself.</span></div>
<div class="line"><a id="l01993" name="l01993"></a><span class="lineno"> 1993</span><span class="comment">   *   - frame_*_sz: We don&#39;t need to use this feature.  Leave at zero.</span></div>
<div class="line"><a id="l01994" name="l01994"></a><span class="lineno"> 1994</span><span class="comment">   *</span></div>
<div class="line"><a id="l01995" name="l01995"></a><span class="lineno"> 1995</span><span class="comment">   * And this must fit into the max sendable blob (send_blob()) or meta-blob (send_native_handle()).</span></div>
<div class="line"><a id="l01996" name="l01996"></a><span class="lineno"> 1996</span><span class="comment">   * And if we might invoke either one, then formally speaking we must report the lower of the two.  So let&#39;s say</span></div>
<div class="line"><a id="l01997" name="l01997"></a><span class="lineno"> 1997</span><span class="comment">   * that&#39;s M.  Hence:</span></div>
<div class="line"><a id="l01998" name="l01998"></a><span class="lineno"> 1998</span><span class="comment">   *   frame_*_sz = 0</span></div>
<div class="line"><a id="l01999" name="l01999"></a><span class="lineno"> 1999</span><span class="comment">   *   segment_sz = M */</span></div>
<div class="line"><a id="l02000" name="l02000"></a><span class="lineno"> 2000</span> </div>
<div class="line"><a id="l02001" name="l02001"></a><span class="lineno"> 2001</span>  <span class="keywordtype">size_t</span> sz;</div>
<div class="line"><a id="l02002" name="l02002"></a><span class="lineno"> 2002</span>  <span class="keywordflow">if</span> <span class="keyword">constexpr</span>(Owned_channel::S_HAS_BLOB_PIPE_ONLY)</div>
<div class="line"><a id="l02003" name="l02003"></a><span class="lineno"> 2003</span>  {</div>
<div class="line"><a id="l02004" name="l02004"></a><span class="lineno"> 2004</span>    <span class="comment">// Only send_native_handle() shall be used.  See send().</span></div>
<div class="line"><a id="l02005" name="l02005"></a><span class="lineno"> 2005</span>    sz = channel.send_blob_max_size();</div>
<div class="line"><a id="l02006" name="l02006"></a><span class="lineno"> 2006</span>  }</div>
<div class="line"><a id="l02007" name="l02007"></a><span class="lineno"> 2007</span>  <span class="keywordflow">else</span> <span class="keywordflow">if</span> <span class="keyword">constexpr</span>(Owned_channel::S_HAS_NATIVE_HANDLE_PIPE_ONLY)</div>
<div class="line"><a id="l02008" name="l02008"></a><span class="lineno"> 2008</span>  {</div>
<div class="line"><a id="l02009" name="l02009"></a><span class="lineno"> 2009</span>    <span class="comment">// Only send_blob() shall be used.  See send().</span></div>
<div class="line"><a id="l02010" name="l02010"></a><span class="lineno"> 2010</span>    sz = channel.send_meta_blob_max_size();</div>
<div class="line"><a id="l02011" name="l02011"></a><span class="lineno"> 2011</span>  }</div>
<div class="line"><a id="l02012" name="l02012"></a><span class="lineno"> 2012</span>  <span class="keywordflow">else</span></div>
<div class="line"><a id="l02013" name="l02013"></a><span class="lineno"> 2013</span>  {</div>
<div class="line"><a id="l02014" name="l02014"></a><span class="lineno"> 2014</span>    <span class="keyword">static_assert</span>(Owned_channel::S_HAS_2_PIPES, <span class="stringliteral">&quot;This code assumes 1 blobs pipe, 1 handles pipe, or both exactly.&quot;</span>);</div>
<div class="line"><a id="l02015" name="l02015"></a><span class="lineno"> 2015</span>    <span class="comment">// Either one may be used.  See send().</span></div>
<div class="line"><a id="l02016" name="l02016"></a><span class="lineno"> 2016</span>    sz = std::min(channel.send_meta_blob_max_size(), channel.send_blob_max_size());</div>
<div class="line"><a id="l02017" name="l02017"></a><span class="lineno"> 2017</span>  }</div>
<div class="line"><a id="l02018" name="l02018"></a><span class="lineno"> 2018</span> </div>
<div class="line"><a id="l02019" name="l02019"></a><span class="lineno"> 2019</span>  <span class="keywordflow">return</span> <a class="code hl_struct" href="structipc_1_1transport_1_1struc_1_1Heap__fixed__builder_1_1Config.html">Heap_fixed_builder::Config</a>{ channel.get_logger(), sz, 0, 0 };</div>
<div class="line"><a id="l02020" name="l02020"></a><span class="lineno"> 2020</span>} <span class="comment">// Channel::heap_fixed_builder_config()</span></div>
<div class="line"><a id="l02021" name="l02021"></a><span class="lineno"> 2021</span> </div>
<div class="line"><a id="l02022" name="l02022"></a><span class="lineno"> 2022</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02023" name="l02023"></a><span class="lineno"> 2023</span><span class="keyword">typename</span> <a class="code hl_struct" href="structipc_1_1transport_1_1struc_1_1Heap__reader_1_1Config.html">Heap_reader::Config</a> <span class="comment">// Static.</span></div>
<div class="line"><a id="l02024" name="l02024"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a629c06957e1c5fac96d62473f7e18966"> 2024</a></span>  CLASS_STRUCTURED_CHANNEL::heap_reader_config(<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4a0188052c15cab70d712f41b0e74ba7">Owned_channel</a>&amp; channel)</div>
<div class="line"><a id="l02025" name="l02025"></a><span class="lineno"> 2025</span>{</div>
<div class="line"><a id="l02026" name="l02026"></a><span class="lineno"> 2026</span>  <span class="keywordflow">return</span> <a class="code hl_struct" href="structipc_1_1transport_1_1struc_1_1Heap__reader_1_1Config.html">Heap_reader::Config</a>{ channel.get_logger(), 0 };</div>
<div class="line"><a id="l02027" name="l02027"></a><span class="lineno"> 2027</span>}</div>
<div class="line"><a id="l02028" name="l02028"></a><span class="lineno"> 2028</span> </div>
<div class="line"><a id="l02029" name="l02029"></a><span class="lineno"> 2029</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02030" name="l02030"></a><span class="lineno"> 2030</span><span class="keyword">const</span> <span class="keyword">typename</span> CLASS_STRUCTURED_CHANNEL::Builder_config&amp;</div>
<div class="line"><a id="l02031" name="l02031"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a969bc2021565c542c902fc14ff711c38"> 2031</a></span>  CLASS_STRUCTURED_CHANNEL::struct_builder_config()<span class="keyword"> const</span></div>
<div class="line"><a id="l02032" name="l02032"></a><span class="lineno"> 2032</span><span class="keyword"></span>{</div>
<div class="line"><a id="l02033" name="l02033"></a><span class="lineno"> 2033</span>  <span class="comment">// Never changes; no need to lock.</span></div>
<div class="line"><a id="l02034" name="l02034"></a><span class="lineno"> 2034</span>  <span class="keywordflow">return</span> m_sync_io.struct_builder_config();</div>
<div class="line"><a id="l02035" name="l02035"></a><span class="lineno"> 2035</span>}</div>
<div class="line"><a id="l02036" name="l02036"></a><span class="lineno"> 2036</span> </div>
<div class="line"><a id="l02037" name="l02037"></a><span class="lineno"> 2037</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02038" name="l02038"></a><span class="lineno"> 2038</span><span class="keyword">const</span> <span class="keyword">typename</span> CLASS_STRUCTURED_CHANNEL::Builder_config::Builder::Session&amp;</div>
<div class="line"><a id="l02039" name="l02039"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ade98da21ce433f8ba338e3139760e94a"> 2039</a></span>  CLASS_STRUCTURED_CHANNEL::struct_lender_session()<span class="keyword"> const</span></div>
<div class="line"><a id="l02040" name="l02040"></a><span class="lineno"> 2040</span><span class="keyword"></span>{</div>
<div class="line"><a id="l02041" name="l02041"></a><span class="lineno"> 2041</span>  <span class="comment">// Never changes; no need to lock.</span></div>
<div class="line"><a id="l02042" name="l02042"></a><span class="lineno"> 2042</span>  <span class="keywordflow">return</span> m_sync_io.struct_lender_session();</div>
<div class="line"><a id="l02043" name="l02043"></a><span class="lineno"> 2043</span>}</div>
<div class="line"><a id="l02044" name="l02044"></a><span class="lineno"> 2044</span> </div>
<div class="line"><a id="l02045" name="l02045"></a><span class="lineno"> 2045</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02046" name="l02046"></a><span class="lineno"> 2046</span><span class="keyword">const</span> <span class="keyword">typename</span> CLASS_STRUCTURED_CHANNEL::Reader_config&amp;</div>
<div class="line"><a id="l02047" name="l02047"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ade9a8f99615d2c53de1a68989376750d"> 2047</a></span>  CLASS_STRUCTURED_CHANNEL::struct_reader_config()<span class="keyword"> const</span></div>
<div class="line"><a id="l02048" name="l02048"></a><span class="lineno"> 2048</span><span class="keyword"></span>{</div>
<div class="line"><a id="l02049" name="l02049"></a><span class="lineno"> 2049</span>  <span class="comment">// Never changes; no need to lock.</span></div>
<div class="line"><a id="l02050" name="l02050"></a><span class="lineno"> 2050</span>  <span class="keywordflow">return</span> m_sync_io.struct_reader_config();</div>
<div class="line"><a id="l02051" name="l02051"></a><span class="lineno"> 2051</span>}</div>
<div class="line"><a id="l02052" name="l02052"></a><span class="lineno"> 2052</span> </div>
<div class="line"><a id="l02053" name="l02053"></a><span class="lineno"> 2053</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02054" name="l02054"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a394e0f9cfa5f9bd4ba9ee17d3d54a8b3"> 2054</a></span><span class="keyword">typename</span> CLASS_STRUCTURED_CHANNEL::Msg_out CLASS_STRUCTURED_CHANNEL::create_msg(<a class="code hl_struct" href="structipc_1_1util_1_1Native__handle.html">Native_handle</a>&amp;&amp; hndl_or_null)<span class="keyword"> const</span></div>
<div class="line"><a id="l02055" name="l02055"></a><span class="lineno"> 2055</span><span class="keyword"></span>{</div>
<div class="line"><a id="l02056" name="l02056"></a><span class="lineno"> 2056</span>  <span class="comment">// Always safe per contract.</span></div>
<div class="line"><a id="l02057" name="l02057"></a><span class="lineno"> 2057</span>  <span class="keywordflow">return</span> m_sync_io.create_msg(std::move(hndl_or_null));</div>
<div class="line"><a id="l02058" name="l02058"></a><span class="lineno"> 2058</span>}</div>
<div class="line"><a id="l02059" name="l02059"></a><span class="lineno"> 2059</span> </div>
<div class="line"><a id="l02060" name="l02060"></a><span class="lineno"> 2060</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02061" name="l02061"></a><span class="lineno"> 2061</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_msg_handler&gt;</div>
<div class="line"><a id="l02062" name="l02062"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a160a8d49624f15a2596ee7b0244584b0"> 2062</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::expect_msg(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">Msg_which_in</a> which, On_msg_handler&amp;&amp; on_msg_func)</div>
<div class="line"><a id="l02063" name="l02063"></a><span class="lineno"> 2063</span>{</div>
<div class="line"><a id="l02064" name="l02064"></a><span class="lineno"> 2064</span>  <span class="keywordflow">return</span> expect_msg_impl&lt;true, On_msg_handler&gt;(which, std::move(on_msg_func));</div>
<div class="line"><a id="l02065" name="l02065"></a><span class="lineno"> 2065</span>}</div>
<div class="line"><a id="l02066" name="l02066"></a><span class="lineno"> 2066</span> </div>
<div class="line"><a id="l02067" name="l02067"></a><span class="lineno"> 2067</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02068" name="l02068"></a><span class="lineno"> 2068</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_msg_handler&gt;</div>
<div class="line"><a id="l02069" name="l02069"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a0054bbf18bc769b2a5b95f249e672c0a"> 2069</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::expect_log_in_request(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">Msg_which_in</a> which, On_msg_handler&amp;&amp; on_log_in_req_func)</div>
<div class="line"><a id="l02070" name="l02070"></a><span class="lineno"> 2070</span>{</div>
<div class="line"><a id="l02071" name="l02071"></a><span class="lineno"> 2071</span>  <span class="keywordflow">return</span> expect_msg_impl&lt;false, On_msg_handler&gt;(which, std::move(on_log_in_req_func));</div>
<div class="line"><a id="l02072" name="l02072"></a><span class="lineno"> 2072</span>}</div>
<div class="line"><a id="l02073" name="l02073"></a><span class="lineno"> 2073</span> </div>
<div class="line"><a id="l02074" name="l02074"></a><span class="lineno"> 2074</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02075" name="l02075"></a><span class="lineno"> 2075</span><span class="keyword">template</span>&lt;<span class="keywordtype">bool</span> MSG_ELSE_LOG_IN, <span class="keyword">typename</span> On_msg_handler&gt;</div>
<div class="line"><a id="l02076" name="l02076"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a8ca2772b0a657cb55f140a6273e528b9"> 2076</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::expect_msg_impl(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">Msg_which_in</a> which, On_msg_handler&amp;&amp; on_msg_func)</div>
<div class="line"><a id="l02077" name="l02077"></a><span class="lineno"> 2077</span>{</div>
<div class="line"><a id="l02078" name="l02078"></a><span class="lineno"> 2078</span>  <span class="keyword">using </span>boost::make_shared;</div>
<div class="line"><a id="l02079" name="l02079"></a><span class="lineno"> 2079</span> </div>
<div class="line"><a id="l02080" name="l02080"></a><span class="lineno"> 2080</span>  <span class="comment">/* We are in thread U or thread W (if invoked from a user handler).</span></div>
<div class="line"><a id="l02081" name="l02081"></a><span class="lineno"> 2081</span><span class="comment">   * Nothing is locked either way due to how we actually invoke user-supplied handlers (which we are about</span></div>
<div class="line"><a id="l02082" name="l02082"></a><span class="lineno"> 2082</span><span class="comment">   * discuss). */</span></div>
<div class="line"><a id="l02083" name="l02083"></a><span class="lineno"> 2083</span> </div>
<div class="line"><a id="l02084" name="l02084"></a><span class="lineno"> 2084</span>  <span class="comment">/* Wrap (a moved version of) their function object in a shared_ptr&lt;Function&lt;&gt;&gt;.  (Perf-wise, ultimately</span></div>
<div class="line"><a id="l02085" name="l02085"></a><span class="lineno"> 2085</span><span class="comment">   * m_sync_io will do this anyway; we probably aren&#39;t adding much churn with this op alone.)</span></div>
<div class="line"><a id="l02086" name="l02086"></a><span class="lineno"> 2086</span><span class="comment">   * Why?  Answer: Unfortunately we have to first pass on_msg_func to m_sync_io.expect_*(); and then possibly</span></div>
<div class="line"><a id="l02087" name="l02087"></a><span class="lineno"> 2087</span><span class="comment">   * also invoke it ourselves -- if message(s) immediately available synchronously.  So we can&#39;t</span></div>
<div class="line"><a id="l02088" name="l02088"></a><span class="lineno"> 2088</span><span class="comment">   * std::move(on_msg_func), as it&#39;ll get blown away (its captures will at least) before we can use it</span></div>
<div class="line"><a id="l02089" name="l02089"></a><span class="lineno"> 2089</span><span class="comment">   * synchronously.  We could capture a copy of on_msg_func, but that is slow: Capturing a copy of a shared_ptr&lt;&gt;</span></div>
<div class="line"><a id="l02090" name="l02090"></a><span class="lineno"> 2090</span><span class="comment">   * is muuuuuch faster. */</span></div>
<div class="line"><a id="l02091" name="l02091"></a><span class="lineno"> 2091</span>  <span class="keyword">auto</span> on_msg_func_ptr = make_shared&lt;On_msg_func&gt;(std::move(on_msg_func));</div>
<div class="line"><a id="l02092" name="l02092"></a><span class="lineno"> 2092</span> </div>
<div class="line"><a id="l02093" name="l02093"></a><span class="lineno"> 2093</span>  <span class="comment">// See below first regarding the purpose of this guy.  Then come back here.</span></div>
<div class="line"><a id="l02094" name="l02094"></a><span class="lineno"> 2094</span>  <span class="keyword">auto</span> real_on_msg_func = [<span class="keyword">this</span>, on_msg_func_ptr](<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a>&amp;&amp; msg_in) <span class="keyword">mutable</span></div>
<div class="line"><a id="l02095" name="l02095"></a><span class="lineno"> 2095</span>  {</div>
<div class="line"><a id="l02096" name="l02096"></a><span class="lineno"> 2096</span>    <span class="comment">// We are in thread W.  m_mutex is locked!</span></div>
<div class="line"><a id="l02097" name="l02097"></a><span class="lineno"> 2097</span> </div>
<div class="line"><a id="l02098" name="l02098"></a><span class="lineno"> 2098</span>    <span class="comment">/* Now comes a key decision: We are in thread W.  We must call user handler on_msg_func().  Thread W isn&#39;t</span></div>
<div class="line"><a id="l02099" name="l02099"></a><span class="lineno"> 2099</span><span class="comment">     * thread U: it isn&#39;t the user thread.  So it would appear we could just straight-up synchronously</span></div>
<div class="line"><a id="l02100" name="l02100"></a><span class="lineno"> 2100</span><span class="comment">     * `on_msg_func(std::move(msg_in))`.  Yet instead we post() onto thread W again -- and do it there.  Why?</span></div>
<div class="line"><a id="l02101" name="l02101"></a><span class="lineno"> 2101</span><span class="comment">     * Answer:</span></div>
<div class="line"><a id="l02102" name="l02102"></a><span class="lineno"> 2102</span><span class="comment">     *</span></div>
<div class="line"><a id="l02103" name="l02103"></a><span class="lineno"> 2103</span><span class="comment">     * Firstly, just technically speaking, m_mutex is locked (we are right now down the call stack from</span></div>
<div class="line"><a id="l02104" name="l02104"></a><span class="lineno"> 2104</span><span class="comment">     * async_wait() handler inside start_ops() statement inside our ctor: it locks m_mutex before calling</span></div>
<div class="line"><a id="l02105" name="l02105"></a><span class="lineno"> 2105</span><span class="comment">     * (*on_active_ev_func)().  So, it being a non-recursive mutex, if they were to call expect_msg(), or</span></div>
<div class="line"><a id="l02106" name="l02106"></a><span class="lineno"> 2106</span><span class="comment">     * send(), or anything else like that -- which they are explicitly allowed to do -- inside such a call</span></div>
<div class="line"><a id="l02107" name="l02107"></a><span class="lineno"> 2107</span><span class="comment">     * we&#39;d deadlock right inside the hypothetical synchronous on_msg_func().</span></div>
<div class="line"><a id="l02108" name="l02108"></a><span class="lineno"> 2108</span><span class="comment">     *</span></div>
<div class="line"><a id="l02109" name="l02109"></a><span class="lineno"> 2109</span><span class="comment">     * However if we post() that onto thread W, then everything is cool.  So at least we know it&#39;s safe.</span></div>
<div class="line"><a id="l02110" name="l02110"></a><span class="lineno"> 2110</span><span class="comment">     * Is it performant?  Before trying to answer that let&#39;s consider the alternative.</span></div>
<div class="line"><a id="l02111" name="l02111"></a><span class="lineno"> 2111</span><span class="comment">     *</span></div>
<div class="line"><a id="l02112" name="l02112"></a><span class="lineno"> 2112</span><span class="comment">     * Sure: we could make m_mutex recursive.  Or we could not-lock it inside our various APIs (including the</span></div>
<div class="line"><a id="l02113" name="l02113"></a><span class="lineno"> 2113</span><span class="comment">     * expect_msg() you&#39;re reading now -- albeit the async-handler inside it), which would be sort-of a user-space</span></div>
<div class="line"><a id="l02114" name="l02114"></a><span class="lineno"> 2114</span><span class="comment">     * recursive mutex action.  So why not?  My (ygoldfel) answer is arguably hand-wavy, but it&#39;s 2-fold.</span></div>
<div class="line"><a id="l02115" name="l02115"></a><span class="lineno"> 2115</span><span class="comment">     * 1, in every instance of my career where I tried to or saw someone tried to solve a deadlocking algorithm</span></div>
<div class="line"><a id="l02116" name="l02116"></a><span class="lineno"> 2116</span><span class="comment">     * by making a recursive mutex, it was the wrong move that was reversed soon enough.  Also generally designs</span></div>
<div class="line"><a id="l02117" name="l02117"></a><span class="lineno"> 2117</span><span class="comment">     * with recursive mutexes that at least appeared to work seemed to do so out of a desire to avoid a few lines</span></div>
<div class="line"><a id="l02118" name="l02118"></a><span class="lineno"> 2118</span><span class="comment">     * of boiler-plate (_impl() methods that had mutex-lock as a pre-condition), in code of quite limited size --</span></div>
<div class="line"><a id="l02119" name="l02119"></a><span class="lineno"> 2119</span><span class="comment">     * not a complex state machine like we have here.  2, while at this exact moment I cannot think of a way</span></div>
<div class="line"><a id="l02120" name="l02120"></a><span class="lineno"> 2120</span><span class="comment">     * that allowing recursive calls into m_sync_io.*() API could lead to algorithmic mayhem/bugs, it is even for me</span></div>
<div class="line"><a id="l02121" name="l02121"></a><span class="lineno"> 2121</span><span class="comment">     * exceedingly difficult to convince myself of that.  It does seem like probably as of this writing Sync_io_obj</span></div>
<div class="line"><a id="l02122" name="l02122"></a><span class="lineno"> 2122</span><span class="comment">     * is pretty clean as far as its algorithm not breaking down due to a handler calling back into its own API -- but</span></div>
<div class="line"><a id="l02123" name="l02123"></a><span class="lineno"> 2123</span><span class="comment">     * will that always be the case?  Will it be reasonable to have to maintain that logic?  It&#39;s mind-breaking.</span></div>
<div class="line"><a id="l02124" name="l02124"></a><span class="lineno"> 2124</span><span class="comment">     *</span></div>
<div class="line"><a id="l02125" name="l02125"></a><span class="lineno"> 2125</span><span class="comment">     * So is the alternative a good idea?  Probably not.  I&#39;d like to prove it beyond a doubt but at the moment can&#39;t.</span></div>
<div class="line"><a id="l02126" name="l02126"></a><span class="lineno"> 2126</span><span class="comment">     * At the very least it is quite difficult to prove that it&#39;s *safe*, as it&#39;s so tough to reason-about due to</span></div>
<div class="line"><a id="l02127" name="l02127"></a><span class="lineno"> 2127</span><span class="comment">     * the flow control layers involved.</span></div>
<div class="line"><a id="l02128" name="l02128"></a><span class="lineno"> 2128</span><span class="comment">     *</span></div>
<div class="line"><a id="l02129" name="l02129"></a><span class="lineno"> 2129</span><span class="comment">     * Okay, so then, back to post()ing it onto thread W.  We know it&#39;s safe.  Is it performant?  The question really</span></div>
<div class="line"><a id="l02130" name="l02130"></a><span class="lineno"> 2130</span><span class="comment">     * applies to the (presumably common) case where the user, in fact, in on_msg_func() does *not* call back into</span></div>
<div class="line"><a id="l02131" name="l02131"></a><span class="lineno"> 2131</span><span class="comment">     * `*this` API -- they are after all encouraged in our class doc header to keep themselves sane by post()ing</span></div>
<div class="line"><a id="l02132" name="l02132"></a><span class="lineno"> 2132</span><span class="comment">     * their true handling onto their thread U (or whatever their equivalent of post()ing is).  So suppose, indeed,</span></div>
<div class="line"><a id="l02133" name="l02133"></a><span class="lineno"> 2133</span><span class="comment">     * their on_msg_func = { &lt;their loop&gt;.post([msg_in = std::move(msg_in)]() { ...handle it...}); }.</span></div>
<div class="line"><a id="l02134" name="l02134"></a><span class="lineno"> 2134</span><span class="comment">     * Indeed we&#39;re adding another m_worker.post() between now and their &quot;...handle it...&quot; actually executing; whereas</span></div>
<div class="line"><a id="l02135" name="l02135"></a><span class="lineno"> 2135</span><span class="comment">     * in *this* particular scenario it would&#39;ve been perfectly safe to just, like, not.</span></div>
<div class="line"><a id="l02136" name="l02136"></a><span class="lineno"> 2136</span><span class="comment">     *</span></div>
<div class="line"><a id="l02137" name="l02137"></a><span class="lineno"> 2137</span><span class="comment">     * So is that delay okay?  In absolute terms I would say... for now at least... yes.  It&#39;ll add a few usec of</span></div>
<div class="line"><a id="l02138" name="l02138"></a><span class="lineno"> 2138</span><span class="comment">     * latency, as boost.asio winds up the stack into Task_engine::run(), then re-enters the post()ed handler of ours</span></div>
<div class="line"><a id="l02139" name="l02139"></a><span class="lineno"> 2139</span><span class="comment">     * and &quot;finally&quot; runs on_msg_func().  It&#39;s boost.asio flow control: it is common in boost.asio/async algorithms</span></div>
<div class="line"><a id="l02140" name="l02140"></a><span class="lineno"> 2140</span><span class="comment">     * as the technique to combat &quot;recursive mayhem.&quot;</span></div>
<div class="line"><a id="l02141" name="l02141"></a><span class="lineno"> 2141</span><span class="comment">     *</span></div>
<div class="line"><a id="l02142" name="l02142"></a><span class="lineno"> 2142</span><span class="comment">     * @todo It is worth revisiting; possibly profiling. */</span></div>
<div class="line"><a id="l02143" name="l02143"></a><span class="lineno"> 2143</span> </div>
<div class="line"><a id="l02144" name="l02144"></a><span class="lineno"> 2144</span>    m_worker.post([<span class="keyword">this</span>, on_msg_func_ptr = std::move(on_msg_func_ptr), msg_in = std::move(msg_in)]() <span class="keyword">mutable</span></div>
<div class="line"><a id="l02145" name="l02145"></a><span class="lineno"> 2145</span>    {</div>
<div class="line"><a id="l02146" name="l02146"></a><span class="lineno"> 2146</span>      <span class="comment">// We are in thread W.  Nothing is locked.</span></div>
<div class="line"><a id="l02147" name="l02147"></a><span class="lineno"> 2147</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Invoking user on-expect-msg handler (async path).&quot;</span>);</div>
<div class="line"><a id="l02148" name="l02148"></a><span class="lineno"> 2148</span>      (*on_msg_func_ptr)(std::move(msg_in));</div>
<div class="line"><a id="l02149" name="l02149"></a><span class="lineno"> 2149</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;Handler completed.&quot;</span>);</div>
<div class="line"><a id="l02150" name="l02150"></a><span class="lineno"> 2150</span>    });</div>
<div class="line"><a id="l02151" name="l02151"></a><span class="lineno"> 2151</span>  }; <span class="comment">// auto real_on_msg_func =</span></div>
<div class="line"><a id="l02152" name="l02152"></a><span class="lineno"> 2152</span> </div>
<div class="line"><a id="l02153" name="l02153"></a><span class="lineno"> 2153</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a> qd_msg;</div>
<div class="line"><a id="l02154" name="l02154"></a><span class="lineno"> 2154</span>  <span class="keywordtype">bool</span> ok;</div>
<div class="line"><a id="l02155" name="l02155"></a><span class="lineno"> 2155</span> </div>
<div class="line"><a id="l02156" name="l02156"></a><span class="lineno"> 2156</span>  <span class="comment">// Reminder: we must protect against concurrent calls from user threads U1, U2, ...; and against access from W.</span></div>
<div class="line"><a id="l02157" name="l02157"></a><span class="lineno"> 2157</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02158" name="l02158"></a><span class="lineno"> 2158</span> </div>
<div class="line"><a id="l02159" name="l02159"></a><span class="lineno"> 2159</span>  <span class="keywordflow">if</span> <span class="keyword">constexpr</span>(MSG_ELSE_LOG_IN)</div>
<div class="line"><a id="l02160" name="l02160"></a><span class="lineno"> 2160</span>  {</div>
<div class="line"><a id="l02161" name="l02161"></a><span class="lineno"> 2161</span>    ok = m_sync_io.expect_msg(which, &amp;qd_msg, std::move(real_on_msg_func));</div>
<div class="line"><a id="l02162" name="l02162"></a><span class="lineno"> 2162</span>  }</div>
<div class="line"><a id="l02163" name="l02163"></a><span class="lineno"> 2163</span>  <span class="keywordflow">else</span></div>
<div class="line"><a id="l02164" name="l02164"></a><span class="lineno"> 2164</span>  {</div>
<div class="line"><a id="l02165" name="l02165"></a><span class="lineno"> 2165</span>    ok = m_sync_io.expect_log_in_request(which, &amp;qd_msg, std::move(real_on_msg_func));</div>
<div class="line"><a id="l02166" name="l02166"></a><span class="lineno"> 2166</span>  }</div>
<div class="line"><a id="l02167" name="l02167"></a><span class="lineno"> 2167</span> </div>
<div class="line"><a id="l02168" name="l02168"></a><span class="lineno"> 2168</span>  <span class="keywordflow">if</span> (!ok)</div>
<div class="line"><a id="l02169" name="l02169"></a><span class="lineno"> 2169</span>  {</div>
<div class="line"><a id="l02170" name="l02170"></a><span class="lineno"> 2170</span>    <span class="keywordflow">return</span> <span class="keyword">false</span>;</div>
<div class="line"><a id="l02171" name="l02171"></a><span class="lineno"> 2171</span>  }</div>
<div class="line"><a id="l02172" name="l02172"></a><span class="lineno"> 2172</span>  <span class="comment">// else:</span></div>
<div class="line"><a id="l02173" name="l02173"></a><span class="lineno"> 2173</span> </div>
<div class="line"><a id="l02174" name="l02174"></a><span class="lineno"> 2174</span>  <span class="keywordflow">if</span> (qd_msg)</div>
<div class="line"><a id="l02175" name="l02175"></a><span class="lineno"> 2175</span>  {</div>
<div class="line"><a id="l02176" name="l02176"></a><span class="lineno"> 2176</span>    <span class="comment">// Message expectation immediately met.  Report it immediately via thread-W (as we always must).</span></div>
<div class="line"><a id="l02177" name="l02177"></a><span class="lineno"> 2177</span>    m_worker.post([<span class="keyword">this</span>, on_msg_func_ptr = std::move(on_msg_func_ptr), msg_in = std::move(qd_msg)]() <span class="keyword">mutable</span></div>
<div class="line"><a id="l02178" name="l02178"></a><span class="lineno"> 2178</span>    {</div>
<div class="line"><a id="l02179" name="l02179"></a><span class="lineno"> 2179</span>      <span class="comment">// We are in thread W.  Nothing is locked.</span></div>
<div class="line"><a id="l02180" name="l02180"></a><span class="lineno"> 2180</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Invoking user on-expect-msg handler (sync path).&quot;</span>);</div>
<div class="line"><a id="l02181" name="l02181"></a><span class="lineno"> 2181</span>      (*on_msg_func_ptr)(std::move(msg_in));</div>
<div class="line"><a id="l02182" name="l02182"></a><span class="lineno"> 2182</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;Handler completed.&quot;</span>);</div>
<div class="line"><a id="l02183" name="l02183"></a><span class="lineno"> 2183</span>    });</div>
<div class="line"><a id="l02184" name="l02184"></a><span class="lineno"> 2184</span>  }</div>
<div class="line"><a id="l02185" name="l02185"></a><span class="lineno"> 2185</span>  <span class="comment">// else { It&#39;ll fire, if ever, asynchronously. }</span></div>
<div class="line"><a id="l02186" name="l02186"></a><span class="lineno"> 2186</span> </div>
<div class="line"><a id="l02187" name="l02187"></a><span class="lineno"> 2187</span>  <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
<div class="line"><a id="l02188" name="l02188"></a><span class="lineno"> 2188</span>} <span class="comment">// Channel::expect_msg_impl()</span></div>
<div class="line"><a id="l02189" name="l02189"></a><span class="lineno"> 2189</span> </div>
<div class="line"><a id="l02190" name="l02190"></a><span class="lineno"> 2190</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02191" name="l02191"></a><span class="lineno"> 2191</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_msg_handler&gt;</div>
<div class="line"><a id="l02192" name="l02192"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a3376b821b129ca3847484a178e080c67"> 2192</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::expect_msgs(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">Msg_which_in</a> which, On_msg_handler&amp;&amp; on_msg_func)</div>
<div class="line"><a id="l02193" name="l02193"></a><span class="lineno"> 2193</span>{</div>
<div class="line"><a id="l02194" name="l02194"></a><span class="lineno"> 2194</span>  <span class="keyword">using </span>boost::make_shared;</div>
<div class="line"><a id="l02195" name="l02195"></a><span class="lineno"> 2195</span> </div>
<div class="line"><a id="l02196" name="l02196"></a><span class="lineno"> 2196</span>  <span class="comment">/* We are in thread U; or thread W (if invoked from a user handler); always serially.</span></div>
<div class="line"><a id="l02197" name="l02197"></a><span class="lineno"> 2197</span><span class="comment">   * Nothing is locked either way due to how we actually invoke user-supplied handlers. */</span></div>
<div class="line"><a id="l02198" name="l02198"></a><span class="lineno"> 2198</span> </div>
<div class="line"><a id="l02199" name="l02199"></a><span class="lineno"> 2199</span>  <span class="comment">// Wrap (a moved version of) their function object in a shared_ptr&lt;Function&lt;&gt;&gt;.  See explanation in expect_msg_impl().</span></div>
<div class="line"><a id="l02200" name="l02200"></a><span class="lineno"> 2200</span>  <span class="keyword">auto</span> on_msg_func_ptr = make_shared&lt;On_msg_func&gt;(std::move(on_msg_func));</div>
<div class="line"><a id="l02201" name="l02201"></a><span class="lineno"> 2201</span> </div>
<div class="line"><a id="l02202" name="l02202"></a><span class="lineno"> 2202</span>  <span class="keyword">auto</span> real_on_msg_func = [<span class="keyword">this</span>, on_msg_func_ptr](<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a>&amp;&amp; msg_in)</div>
<div class="line"><a id="l02203" name="l02203"></a><span class="lineno"> 2203</span>  {</div>
<div class="line"><a id="l02204" name="l02204"></a><span class="lineno"> 2204</span>    <span class="comment">// We are in thread W.  m_mutex is locked!</span></div>
<div class="line"><a id="l02205" name="l02205"></a><span class="lineno"> 2205</span> </div>
<div class="line"><a id="l02206" name="l02206"></a><span class="lineno"> 2206</span>    <span class="comment">/* *Please* see comment in expect_msg_impl() similar spot regarding why we post() here.</span></div>
<div class="line"><a id="l02207" name="l02207"></a><span class="lineno"> 2207</span><span class="comment">     *</span></div>
<div class="line"><a id="l02208" name="l02208"></a><span class="lineno"> 2208</span><span class="comment">     * Orthogonally: The function where this comment sits may be executed 2+ times, unlike expect_msg_impl() which</span></div>
<div class="line"><a id="l02209" name="l02209"></a><span class="lineno"> 2209</span><span class="comment">     * is a one-off message expectation.  So we cannot move(on_msg_func_ptr) -- it&#39;ll get nullified the first time,</span></div>
<div class="line"><a id="l02210" name="l02210"></a><span class="lineno"> 2210</span><span class="comment">     * and you&#39;re screwed.  In expect_msg() we can though for a bit of extra perf. */</span></div>
<div class="line"><a id="l02211" name="l02211"></a><span class="lineno"> 2211</span>    m_worker.post([<span class="keyword">this</span>, on_msg_func_ptr, msg_in = std::move(msg_in)]() <span class="keyword">mutable</span></div>
<div class="line"><a id="l02212" name="l02212"></a><span class="lineno"> 2212</span>    {</div>
<div class="line"><a id="l02213" name="l02213"></a><span class="lineno"> 2213</span>      <span class="comment">// We are in thread W.  Nothing is locked.</span></div>
<div class="line"><a id="l02214" name="l02214"></a><span class="lineno"> 2214</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Invoking user on-expect-msgs handler (async path).&quot;</span>);</div>
<div class="line"><a id="l02215" name="l02215"></a><span class="lineno"> 2215</span>      (*on_msg_func_ptr)(std::move(msg_in));</div>
<div class="line"><a id="l02216" name="l02216"></a><span class="lineno"> 2216</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;Handler completed.&quot;</span>);</div>
<div class="line"><a id="l02217" name="l02217"></a><span class="lineno"> 2217</span>    });</div>
<div class="line"><a id="l02218" name="l02218"></a><span class="lineno"> 2218</span>  };</div>
<div class="line"><a id="l02219" name="l02219"></a><span class="lineno"> 2219</span> </div>
<div class="line"><a id="l02220" name="l02220"></a><span class="lineno"> 2220</span>  <span class="keyword">typename</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a4ab778bce8d7e6e84788879fedc62745">Sync_io_obj::Msgs_in</a> qd_msgs;</div>
<div class="line"><a id="l02221" name="l02221"></a><span class="lineno"> 2221</span> </div>
<div class="line"><a id="l02222" name="l02222"></a><span class="lineno"> 2222</span>  <span class="comment">// Reminder: we must protect against concurrent calls from user threads U1, U2, ...; and against access from W.</span></div>
<div class="line"><a id="l02223" name="l02223"></a><span class="lineno"> 2223</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02224" name="l02224"></a><span class="lineno"> 2224</span> </div>
<div class="line"><a id="l02225" name="l02225"></a><span class="lineno"> 2225</span>  <span class="keywordflow">if</span> (!m_sync_io.expect_msgs(which, &amp;qd_msgs, std::move(real_on_msg_func)))</div>
<div class="line"><a id="l02226" name="l02226"></a><span class="lineno"> 2226</span>  {</div>
<div class="line"><a id="l02227" name="l02227"></a><span class="lineno"> 2227</span>    <span class="keywordflow">return</span> <span class="keyword">false</span>;</div>
<div class="line"><a id="l02228" name="l02228"></a><span class="lineno"> 2228</span>  }</div>
<div class="line"><a id="l02229" name="l02229"></a><span class="lineno"> 2229</span>  <span class="comment">// else:</span></div>
<div class="line"><a id="l02230" name="l02230"></a><span class="lineno"> 2230</span> </div>
<div class="line"><a id="l02231" name="l02231"></a><span class="lineno"> 2231</span>  <span class="keywordflow">if</span> (qd_msgs.empty())</div>
<div class="line"><a id="l02232" name="l02232"></a><span class="lineno"> 2232</span>  {</div>
<div class="line"><a id="l02233" name="l02233"></a><span class="lineno"> 2233</span>    <span class="keywordflow">return</span> <span class="keyword">true</span>; <span class="comment">// They may fire asynchronously.  Nothing for now.</span></div>
<div class="line"><a id="l02234" name="l02234"></a><span class="lineno"> 2234</span>  }</div>
<div class="line"><a id="l02235" name="l02235"></a><span class="lineno"> 2235</span>  <span class="comment">// else</span></div>
<div class="line"><a id="l02236" name="l02236"></a><span class="lineno"> 2236</span> </div>
<div class="line"><a id="l02237" name="l02237"></a><span class="lineno"> 2237</span>  <span class="comment">// Message expectation immediately met.  Report these immediately via thread-W (as we always must).</span></div>
<div class="line"><a id="l02238" name="l02238"></a><span class="lineno"> 2238</span>  m_worker.post([<span class="keyword">this</span>, on_msg_func_ptr = std::move(on_msg_func_ptr), qd_msgs = std::move(qd_msgs)]() <span class="keyword">mutable</span></div>
<div class="line"><a id="l02239" name="l02239"></a><span class="lineno"> 2239</span>  {</div>
<div class="line"><a id="l02240" name="l02240"></a><span class="lineno"> 2240</span>    <span class="comment">// We are in thread W.  Nothing is locked.</span></div>
<div class="line"><a id="l02241" name="l02241"></a><span class="lineno"> 2241</span> </div>
<div class="line"><a id="l02242" name="l02242"></a><span class="lineno"> 2242</span>    <span class="keywordtype">size_t</span> idx = 0;</div>
<div class="line"><a id="l02243" name="l02243"></a><span class="lineno"> 2243</span>    <span class="keywordflow">for</span> (<span class="keyword">auto</span>&amp; msg_in : qd_msgs)</div>
<div class="line"><a id="l02244" name="l02244"></a><span class="lineno"> 2244</span>    {</div>
<div class="line"><a id="l02245" name="l02245"></a><span class="lineno"> 2245</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Invoking user on-expect-msg handler (sync path): &quot;</span></div>
<div class="line"><a id="l02246" name="l02246"></a><span class="lineno"> 2246</span>                     <span class="stringliteral">&quot;handler [&quot;</span> &lt;&lt; idx &lt;&lt; <span class="stringliteral">&quot;] (0-based) of [&quot;</span> &lt;&lt; qd_msgs.size() &lt;&lt; <span class="stringliteral">&quot;] (1-based).&quot;</span>);</div>
<div class="line"><a id="l02247" name="l02247"></a><span class="lineno"> 2247</span>      (*on_msg_func_ptr)(std::move(msg_in));</div>
<div class="line"><a id="l02248" name="l02248"></a><span class="lineno"> 2248</span> </div>
<div class="line"><a id="l02249" name="l02249"></a><span class="lineno"> 2249</span>      ++idx;</div>
<div class="line"><a id="l02250" name="l02250"></a><span class="lineno"> 2250</span>    }</div>
<div class="line"><a id="l02251" name="l02251"></a><span class="lineno"> 2251</span>    FLOW_LOG_TRACE(<span class="stringliteral">&quot;Handlers completed.&quot;</span>);</div>
<div class="line"><a id="l02252" name="l02252"></a><span class="lineno"> 2252</span>  });</div>
<div class="line"><a id="l02253" name="l02253"></a><span class="lineno"> 2253</span> </div>
<div class="line"><a id="l02254" name="l02254"></a><span class="lineno"> 2254</span>  <span class="comment">// Plus more may fire asynchronously.</span></div>
<div class="line"><a id="l02255" name="l02255"></a><span class="lineno"> 2255</span> </div>
<div class="line"><a id="l02256" name="l02256"></a><span class="lineno"> 2256</span>  <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
<div class="line"><a id="l02257" name="l02257"></a><span class="lineno"> 2257</span>} <span class="comment">// Channel::expect_msgs()</span></div>
<div class="line"><a id="l02258" name="l02258"></a><span class="lineno"> 2258</span> </div>
<div class="line"><a id="l02259" name="l02259"></a><span class="lineno"> 2259</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02260" name="l02260"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a896bb326a58f433bade75b62f1893462"> 2260</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::undo_expect_msgs(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">Msg_which_in</a> which)</div>
<div class="line"><a id="l02261" name="l02261"></a><span class="lineno"> 2261</span>{</div>
<div class="line"><a id="l02262" name="l02262"></a><span class="lineno"> 2262</span>  <span class="comment">// Reminder: we must protect against concurrent calls from user threads U1, U2, ...; and against access from W.</span></div>
<div class="line"><a id="l02263" name="l02263"></a><span class="lineno"> 2263</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02264" name="l02264"></a><span class="lineno"> 2264</span>  <span class="keywordflow">return</span> m_sync_io.undo_expect_msgs(which);</div>
<div class="line"><a id="l02265" name="l02265"></a><span class="lineno"> 2265</span>}</div>
<div class="line"><a id="l02266" name="l02266"></a><span class="lineno"> 2266</span> </div>
<div class="line"><a id="l02267" name="l02267"></a><span class="lineno"> 2267</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02268" name="l02268"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a34780bd3507a571cb719ce1d59e5d56f"> 2268</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::undo_expect_responses(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4d4995b27b7a6944fbcceee7657f6413">msg_id_out_t</a> originating_msg_id)</div>
<div class="line"><a id="l02269" name="l02269"></a><span class="lineno"> 2269</span>{</div>
<div class="line"><a id="l02270" name="l02270"></a><span class="lineno"> 2270</span>  <span class="comment">// Reminder: we must protect against concurrent calls from user threads U1, U2, ...; and against access from W.</span></div>
<div class="line"><a id="l02271" name="l02271"></a><span class="lineno"> 2271</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02272" name="l02272"></a><span class="lineno"> 2272</span>  <span class="keywordflow">return</span> m_sync_io.undo_expect_responses(originating_msg_id);</div>
<div class="line"><a id="l02273" name="l02273"></a><span class="lineno"> 2273</span>}</div>
<div class="line"><a id="l02274" name="l02274"></a><span class="lineno"> 2274</span> </div>
<div class="line"><a id="l02275" name="l02275"></a><span class="lineno"> 2275</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02276" name="l02276"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae645cb58ad9ea6374970f1f32c5da448"> 2276</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::send(<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">Msg_out</a>&amp; msg, <span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a05d1cd2fc6a81a39c50a24322fb5c165">Msg_in</a>* originating_msg_or_null, <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a>* err_code)</div>
<div class="line"><a id="l02277" name="l02277"></a><span class="lineno"> 2277</span>{</div>
<div class="line"><a id="l02278" name="l02278"></a><span class="lineno"> 2278</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02279" name="l02279"></a><span class="lineno"> 2279</span>  <span class="keywordflow">return</span> m_sync_io.send(msg, originating_msg_or_null, err_code);</div>
<div class="line"><a id="l02280" name="l02280"></a><span class="lineno"> 2280</span>}</div>
<div class="line"><a id="l02281" name="l02281"></a><span class="lineno"> 2281</span> </div>
<div class="line"><a id="l02282" name="l02282"></a><span class="lineno"> 2282</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02283" name="l02283"></a><span class="lineno"> 2283</span><span class="keyword">typename</span> CLASS_STRUCTURED_CHANNEL::Msg_in_ptr</div>
<div class="line"><a id="l02284" name="l02284"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#aa41aee3c76035f43833078e625e6ef78"> 2284</a></span>  CLASS_STRUCTURED_CHANNEL::sync_request(<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">Msg_out</a>&amp; msg, <span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a05d1cd2fc6a81a39c50a24322fb5c165">Msg_in</a>* originating_msg_or_null,</div>
<div class="line"><a id="l02285" name="l02285"></a><span class="lineno"> 2285</span>                                         <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a>* err_code)</div>
<div class="line"><a id="l02286" name="l02286"></a><span class="lineno"> 2286</span>{</div>
<div class="line"><a id="l02287" name="l02287"></a><span class="lineno"> 2287</span>  <span class="keywordflow">return</span> sync_request(msg, originating_msg_or_null, util::Fine_duration::max(), err_code);</div>
<div class="line"><a id="l02288" name="l02288"></a><span class="lineno"> 2288</span>}</div>
<div class="line"><a id="l02289" name="l02289"></a><span class="lineno"> 2289</span> </div>
<div class="line"><a id="l02290" name="l02290"></a><span class="lineno"> 2290</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02291" name="l02291"></a><span class="lineno"> 2291</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_msg_handler&gt;</div>
<div class="line"><a id="l02292" name="l02292"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a97506bcb695f22e7ca6b480bae5b2346"> 2292</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::async_request</div>
<div class="line"><a id="l02293" name="l02293"></a><span class="lineno"> 2293</span>       (<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">Msg_out</a>&amp; msg, <span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a05d1cd2fc6a81a39c50a24322fb5c165">Msg_in</a>* originating_msg_or_null,</div>
<div class="line"><a id="l02294" name="l02294"></a><span class="lineno"> 2294</span>        <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4d4995b27b7a6944fbcceee7657f6413">msg_id_out_t</a>* id_unless_one_off, On_msg_handler&amp;&amp; on_rsp_func, <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a>* err_code)</div>
<div class="line"><a id="l02295" name="l02295"></a><span class="lineno"> 2295</span>{</div>
<div class="line"><a id="l02296" name="l02296"></a><span class="lineno"> 2296</span>  <span class="keyword">using </span>boost::make_shared;</div>
<div class="line"><a id="l02297" name="l02297"></a><span class="lineno"> 2297</span> </div>
<div class="line"><a id="l02298" name="l02298"></a><span class="lineno"> 2298</span>  <span class="comment">/* We are in thread U; or thread W (if invoked from a user handler).</span></div>
<div class="line"><a id="l02299" name="l02299"></a><span class="lineno"> 2299</span><span class="comment">   * Nothing is locked either way due to how we actually invoke user-supplied handlers. */</span></div>
<div class="line"><a id="l02300" name="l02300"></a><span class="lineno"> 2300</span> </div>
<div class="line"><a id="l02301" name="l02301"></a><span class="lineno"> 2301</span>  <span class="comment">/* This is one of the 2 interesting send methods (the other being sync_request() which is a whole other thing).</span></div>
<div class="line"><a id="l02302" name="l02302"></a><span class="lineno"> 2302</span><span class="comment">   * That is we can&#39;t just forward to m_sync_io.async_request() all the way, tempting as it is.  The reason is the same</span></div>
<div class="line"><a id="l02303" name="l02303"></a><span class="lineno"> 2303</span><span class="comment">   * as in expect_msg_impl() and expects_msgs() (at least): if we just forward on_rsp_func, it will run in thread W</span></div>
<div class="line"><a id="l02304" name="l02304"></a><span class="lineno"> 2304</span><span class="comment">   * as desired, but m_mutex will be locked already... and... therefore just *please* see the comment about why</span></div>
<div class="line"><a id="l02305" name="l02305"></a><span class="lineno"> 2305</span><span class="comment">   * we post(), in expect_msg_impl().  Same deal here.  (We should add: if for some reason we crazily decided to</span></div>
<div class="line"><a id="l02306" name="l02306"></a><span class="lineno"> 2306</span><span class="comment">   * post() in (e.g.) expect_msg_impl() but not here, then handlers could fire out of order (and did, in testing</span></div>
<div class="line"><a id="l02307" name="l02307"></a><span class="lineno"> 2307</span><span class="comment">   * before fixing it): A successful async-firing expect_msg_impl() post()s the true user handler onto W; then</span></div>
<div class="line"><a id="l02308" name="l02308"></a><span class="lineno"> 2308</span><span class="comment">   * say a response to this async_request() is already in the in-pipe, so m_sync_io reads it and therefore executes</span></div>
<div class="line"><a id="l02309" name="l02309"></a><span class="lineno"> 2309</span><span class="comment">   * on_rsp_func() synchronously.  Only then would the post()ed notification (expect_msg_impl()) handler run, once we</span></div>
<div class="line"><a id="l02310" name="l02310"></a><span class="lineno"> 2310</span><span class="comment">   * got out of the boost.asio task.  That would be a bug, even supposing we didn&#39;t run into m_mutex deadlock (which</span></div>
<div class="line"><a id="l02311" name="l02311"></a><span class="lineno"> 2311</span><span class="comment">   * would only occur if they actually tried to use a *this API from directly in on_rsp_func().  I digress though.)</span></div>
<div class="line"><a id="l02312" name="l02312"></a><span class="lineno"> 2312</span><span class="comment">   *</span></div>
<div class="line"><a id="l02313" name="l02313"></a><span class="lineno"> 2313</span><span class="comment">   * The other thing to take care of is is the non-one-off mode of this async_request(): It can fire multiple times; so</span></div>
<div class="line"><a id="l02314" name="l02314"></a><span class="lineno"> 2314</span><span class="comment">   * either (as in expect_msgs()) we either have to make copies of on_rsp_func and all its captures (expensive) or</span></div>
<div class="line"><a id="l02315" name="l02315"></a><span class="lineno"> 2315</span><span class="comment">   * move()it, but move()ing it would blow away the captures and be a bug.  m_sync_io, like our own expect_msgs(),</span></div>
<div class="line"><a id="l02316" name="l02316"></a><span class="lineno"> 2316</span><span class="comment">   * deals with the same thing internally.  So all 3 piece of code do the same thing: wrap on_rsp_func into</span></div>
<div class="line"><a id="l02317" name="l02317"></a><span class="lineno"> 2317</span><span class="comment">   * a shared_ptr, so that we copy `shared_ptr`s around -- cheap compared to copying function objects.</span></div>
<div class="line"><a id="l02318" name="l02318"></a><span class="lineno"> 2318</span><span class="comment">   *</span></div>
<div class="line"><a id="l02319" name="l02319"></a><span class="lineno"> 2319</span><span class="comment">   * Don&#39;t bother complicating the code by not-shared_ptr-wrapping in one-off mode.  In addition to being more</span></div>
<div class="line"><a id="l02320" name="l02320"></a><span class="lineno"> 2320</span><span class="comment">   * complex, there&#39;s no proof that doing 2 move(on_rsp_func)s is faster than 1 such move() + some shared_ptr</span></div>
<div class="line"><a id="l02321" name="l02321"></a><span class="lineno"> 2321</span><span class="comment">   * transfer(s). */</span></div>
<div class="line"><a id="l02322" name="l02322"></a><span class="lineno"> 2322</span> </div>
<div class="line"><a id="l02323" name="l02323"></a><span class="lineno"> 2323</span>  <span class="keyword">auto</span> real_on_rsp_func = [<span class="keyword">this</span>,</div>
<div class="line"><a id="l02324" name="l02324"></a><span class="lineno"> 2324</span>                           on_rsp_func_ptr = make_shared&lt;On_msg_func&gt;(std::move(on_rsp_func))] <span class="comment">// Per 2nd para above.</span></div>
<div class="line"><a id="l02325" name="l02325"></a><span class="lineno"> 2325</span>                             (<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a>&amp;&amp; msg_in)</div>
<div class="line"><a id="l02326" name="l02326"></a><span class="lineno"> 2326</span>  {</div>
<div class="line"><a id="l02327" name="l02327"></a><span class="lineno"> 2327</span>    <span class="comment">// We are in thread W.  m_mutex is locked!</span></div>
<div class="line"><a id="l02328" name="l02328"></a><span class="lineno"> 2328</span> </div>
<div class="line"><a id="l02329" name="l02329"></a><span class="lineno"> 2329</span>    <span class="comment">// @todo Could save a few cycles by doing `on_rsp_func_ptr = move(on_rsp_func_ptr)` instead if one-off mode.</span></div>
<div class="line"><a id="l02330" name="l02330"></a><span class="lineno"> 2330</span>    m_worker.post([<span class="keyword">this</span>, on_rsp_func_ptr, msg_in = std::move(msg_in)]() <span class="keyword">mutable</span></div>
<div class="line"><a id="l02331" name="l02331"></a><span class="lineno"> 2331</span>    {</div>
<div class="line"><a id="l02332" name="l02332"></a><span class="lineno"> 2332</span>      <span class="comment">// We are in thread W.  Nothing is locked.</span></div>
<div class="line"><a id="l02333" name="l02333"></a><span class="lineno"> 2333</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Invoking user on-rsp handler.&quot;</span>);</div>
<div class="line"><a id="l02334" name="l02334"></a><span class="lineno"> 2334</span>      (*on_rsp_func_ptr)(std::move(msg_in));</div>
<div class="line"><a id="l02335" name="l02335"></a><span class="lineno"> 2335</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;Handler completed.&quot;</span>);</div>
<div class="line"><a id="l02336" name="l02336"></a><span class="lineno"> 2336</span>    });</div>
<div class="line"><a id="l02337" name="l02337"></a><span class="lineno"> 2337</span>  }; <span class="comment">// auto real_on_rsp_func()</span></div>
<div class="line"><a id="l02338" name="l02338"></a><span class="lineno"> 2338</span> </div>
<div class="line"><a id="l02339" name="l02339"></a><span class="lineno"> 2339</span>  <span class="comment">// Reminder: we must protect against concurrent calls from user threads U1, U2, ...; and against access from W.</span></div>
<div class="line"><a id="l02340" name="l02340"></a><span class="lineno"> 2340</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02341" name="l02341"></a><span class="lineno"> 2341</span>  <span class="keywordflow">return</span> m_sync_io.async_request(msg, originating_msg_or_null,</div>
<div class="line"><a id="l02342" name="l02342"></a><span class="lineno"> 2342</span>                                 id_unless_one_off, std::move(real_on_rsp_func), err_code);</div>
<div class="line"><a id="l02343" name="l02343"></a><span class="lineno"> 2343</span>} <span class="comment">// Channel::async_request()</span></div>
<div class="line"><a id="l02344" name="l02344"></a><span class="lineno"> 2344</span> </div>
<div class="line"><a id="l02345" name="l02345"></a><span class="lineno"> 2345</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02346" name="l02346"></a><span class="lineno"> 2346</span><span class="keyword">typename</span> CLASS_STRUCTURED_CHANNEL::Msg_in_ptr</div>
<div class="line"><a id="l02347" name="l02347"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a18100e5af4f5111f1515ff9eef8b1f92"> 2347</a></span>  CLASS_STRUCTURED_CHANNEL::sync_request(<span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">Msg_out</a>&amp; msg, <span class="keyword">const</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a05d1cd2fc6a81a39c50a24322fb5c165">Msg_in</a>* originating_msg_or_null,</div>
<div class="line"><a id="l02348" name="l02348"></a><span class="lineno"> 2348</span>                                         <a class="code hl_typedef" href="namespaceipc_1_1util.html#ac66141280c3b7295a86b65209f31cc58">util::Fine_duration</a> timeout, <a class="code hl_typedef" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a>* err_code)</div>
<div class="line"><a id="l02349" name="l02349"></a><span class="lineno"> 2349</span>{</div>
<div class="line"><a id="l02350" name="l02350"></a><span class="lineno"> 2350</span>  <span class="keyword">using </span>Request_result = <span class="keyword">typename</span> <a class="code hl_struct" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_1_1Request__result.html">Sync_op_state::Request_result</a>;</div>
<div class="line"><a id="l02351" name="l02351"></a><span class="lineno"> 2351</span>  <span class="keyword">using </span><a class="code hl_typedef" href="namespaceipc_1_1util.html#ac66141280c3b7295a86b65209f31cc58">util::Fine_duration</a>;</div>
<div class="line"><a id="l02352" name="l02352"></a><span class="lineno"> 2352</span>  <span class="keyword">using </span>boost::promise;</div>
<div class="line"><a id="l02353" name="l02353"></a><span class="lineno"> 2353</span>  <span class="keyword">using </span>boost::chrono::round;</div>
<div class="line"><a id="l02354" name="l02354"></a><span class="lineno"> 2354</span>  <span class="keyword">using </span>boost::chrono::milliseconds;</div>
<div class="line"><a id="l02355" name="l02355"></a><span class="lineno"> 2355</span>  <span class="keyword">using </span>boost::unique_future;</div>
<div class="line"><a id="l02356" name="l02356"></a><span class="lineno"> 2356</span>  <span class="keyword">using </span>std::holds_alternative;</div>
<div class="line"><a id="l02357" name="l02357"></a><span class="lineno"> 2357</span>  <span class="keyword">using </span>std::get;</div>
<div class="line"><a id="l02358" name="l02358"></a><span class="lineno"> 2358</span>  <span class="keyword">using </span>std::monostate;</div>
<div class="line"><a id="l02359" name="l02359"></a><span class="lineno"> 2359</span> </div>
<div class="line"><a id="l02360" name="l02360"></a><span class="lineno"> 2360</span>  FLOW_ERROR_EXEC_AND_THROW_ON_ERROR(<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a>, sync_request, msg, originating_msg_or_null, timeout, _1);</div>
<div class="line"><a id="l02361" name="l02361"></a><span class="lineno"> 2361</span>  <span class="comment">// ^-- Call ourselves and return if err_code is null.  If got to present line, err_code is not null.</span></div>
<div class="line"><a id="l02362" name="l02362"></a><span class="lineno"> 2362</span> </div>
<div class="line"><a id="l02363" name="l02363"></a><span class="lineno"> 2363</span>  <span class="comment">// We are in thread U (not W, by contract, as blocking thread W can delay subsequent handler firing).</span></div>
<div class="line"><a id="l02364" name="l02364"></a><span class="lineno"> 2364</span> </div>
<div class="line"><a id="l02365" name="l02365"></a><span class="lineno"> 2365</span>  <span class="comment">// We comment inline but see m_sync_op_state doc header for overview.</span></div>
<div class="line"><a id="l02366" name="l02366"></a><span class="lineno"> 2366</span> </div>
<div class="line"><a id="l02367" name="l02367"></a><span class="lineno"> 2367</span>  <span class="comment">/* Explicitly make all (even blocking) sync_request()s serially execute.</span></div>
<div class="line"><a id="l02368" name="l02368"></a><span class="lineno"> 2368</span><span class="comment">   * Cannot use m_mutex for this: we promised to allow other APIs (non-blocking ones, e.g., send()) to execute</span></div>
<div class="line"><a id="l02369" name="l02369"></a><span class="lineno"> 2369</span><span class="comment">   * immediately if invoked during our potential blocking wait below.  So m_mutex is to be locked before the wait</span></div>
<div class="line"><a id="l02370" name="l02370"></a><span class="lineno"> 2370</span><span class="comment">   * and after the wait, not during. */</span></div>
<div class="line"><a id="l02371" name="l02371"></a><span class="lineno"> 2371</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> sync_op_lock(m_sync_op_mutex);</div>
<div class="line"><a id="l02372" name="l02372"></a><span class="lineno"> 2372</span> </div>
<div class="line"><a id="l02373" name="l02373"></a><span class="lineno"> 2373</span>  unique_future&lt;void&gt; done_future;</div>
<div class="line"><a id="l02374" name="l02374"></a><span class="lineno"> 2374</span>  <span class="keywordtype">bool</span> send_tried;</div>
<div class="line"><a id="l02375" name="l02375"></a><span class="lineno"> 2375</span>  <span class="keyword">typename</span> <a class="code hl_typedef" href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#a6b5142da7049fc212faff3914e69379b">Sync_op_state::id_t</a> id;</div>
<div class="line"><a id="l02376" name="l02376"></a><span class="lineno"> 2376</span>  {</div>
<div class="line"><a id="l02377" name="l02377"></a><span class="lineno"> 2377</span>    <span class="comment">// Reminder: we must protect against concurrent calls from user threads U1, U2, ...; and against access from W.</span></div>
<div class="line"><a id="l02378" name="l02378"></a><span class="lineno"> 2378</span>    <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex); <span class="comment">// Protect m_sync_io, m_sync_op_state....</span></div>
<div class="line"><a id="l02379" name="l02379"></a><span class="lineno"> 2379</span> </div>
<div class="line"><a id="l02380" name="l02380"></a><span class="lineno"> 2380</span>    assert((!m_sync_op_state)</div>
<div class="line"><a id="l02381" name="l02381"></a><span class="lineno"> 2381</span>           &amp;&amp; <span class="stringliteral">&quot;We should have prevented concurrent execution of sync_request() body via m_sync_op_mutex.&quot;</span>);</div>
<div class="line"><a id="l02382" name="l02382"></a><span class="lineno"> 2382</span> </div>
<div class="line"><a id="l02383" name="l02383"></a><span class="lineno"> 2383</span>    <span class="comment">/* Set up the state for this sync-op.  Since from the moment m_sync_io.async_request() (below) successfully returns</span></div>
<div class="line"><a id="l02384" name="l02384"></a><span class="lineno"> 2384</span><span class="comment">     * technically a response can immediately arrive in thread W we need to do this before that async_request(). */</span></div>
<div class="line"><a id="l02385" name="l02385"></a><span class="lineno"> 2385</span> </div>
<div class="line"><a id="l02386" name="l02386"></a><span class="lineno"> 2386</span>    m_sync_op_state = { <span class="keywordtype">id</span> = m_sync_op_state_id++,</div>
<div class="line"><a id="l02387" name="l02387"></a><span class="lineno"> 2387</span>                        {}, <span class="comment">// Start at default-cted variant (monostate).</span></div>
<div class="line"><a id="l02388" name="l02388"></a><span class="lineno"> 2388</span>                        {} }; <span class="comment">// New `promise`.</span></div>
<div class="line"><a id="l02389" name="l02389"></a><span class="lineno"> 2389</span>    done_future = m_sync_op_state-&gt;m_op_done_signal.get_future();</div>
<div class="line"><a id="l02390" name="l02390"></a><span class="lineno"> 2390</span> </div>
<div class="line"><a id="l02391" name="l02391"></a><span class="lineno"> 2391</span>    <span class="comment">// (Do not use this-&gt;async_request() -- it would re-lock m_mutex.)</span></div>
<div class="line"><a id="l02392" name="l02392"></a><span class="lineno"> 2392</span>    send_tried = m_sync_io.async_request(msg, originating_msg_or_null, <span class="keyword">nullptr</span>, <span class="comment">// One-off response expectation.</span></div>
<div class="line"><a id="l02393" name="l02393"></a><span class="lineno"> 2393</span>                                         [<span class="keyword">this</span>, <span class="keywordtype">id</span>](<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a>&amp;&amp; msg_in)</div>
<div class="line"><a id="l02394" name="l02394"></a><span class="lineno"> 2394</span>    {</div>
<div class="line"><a id="l02395" name="l02395"></a><span class="lineno"> 2395</span>      <span class="comment">// We are in thread W.  m_mutex is locked!</span></div>
<div class="line"><a id="l02396" name="l02396"></a><span class="lineno"> 2396</span> </div>
<div class="line"><a id="l02397" name="l02397"></a><span class="lineno"> 2397</span>      <span class="comment">/* id was generated by sync_request() (see above).  And now a response to it is here:</span></div>
<div class="line"><a id="l02398" name="l02398"></a><span class="lineno"> 2398</span><span class="comment">       * internally m_sync_io has unregistered the response expectation, as it is a one-off.</span></div>
<div class="line"><a id="l02399" name="l02399"></a><span class="lineno"> 2399</span><span class="comment">       * Now we just need to load the result and tickle the waiting sync_request() in thread U.</span></div>
<div class="line"><a id="l02400" name="l02400"></a><span class="lineno"> 2400</span><span class="comment">       * That is unless it has already timed out. */</span></div>
<div class="line"><a id="l02401" name="l02401"></a><span class="lineno"> 2401</span>      promise&lt;void&gt; op_done_signal;</div>
<div class="line"><a id="l02402" name="l02402"></a><span class="lineno"> 2402</span> </div>
<div class="line"><a id="l02403" name="l02403"></a><span class="lineno"> 2403</span>      <span class="comment">/* Ensure we won the race against:</span></div>
<div class="line"><a id="l02404" name="l02404"></a><span class="lineno"> 2404</span><span class="comment">       *   - timeout (sync_request() itself, see timeout handling below);</span></div>
<div class="line"><a id="l02405" name="l02405"></a><span class="lineno"> 2405</span><span class="comment">       *   - incoming-direction error (see start()).</span></div>
<div class="line"><a id="l02406" name="l02406"></a><span class="lineno"> 2406</span><span class="comment">       * If timeout happened, either !m_sync_op_state; or a new m_sync_op_state exists because of an even later</span></div>
<div class="line"><a id="l02407" name="l02407"></a><span class="lineno"> 2407</span><span class="comment">       * sync_request().  If error happened, and sync_request() hasn&#39;t fished it out yet, then the result will</span></div>
<div class="line"><a id="l02408" name="l02408"></a><span class="lineno"> 2408</span><span class="comment">       * already be an Error_code. */</span></div>
<div class="line"><a id="l02409" name="l02409"></a><span class="lineno"> 2409</span>      <span class="keywordflow">if</span> ((!m_sync_op_state) || (m_sync_op_state-&gt;m_id != <span class="keywordtype">id</span>)</div>
<div class="line"><a id="l02410" name="l02410"></a><span class="lineno"> 2410</span>          || holds_alternative&lt;Error_code&gt;(m_sync_op_state-&gt;m_result_if_any))</div>
<div class="line"><a id="l02411" name="l02411"></a><span class="lineno"> 2411</span>      {</div>
<div class="line"><a id="l02412" name="l02412"></a><span class="lineno"> 2412</span>        <span class="comment">/* @todo Barring in-direction error occurring earlier -- not even sure that is really possible -- in case</span></div>
<div class="line"><a id="l02413" name="l02413"></a><span class="lineno"> 2413</span><span class="comment">         * of timeout:</span></div>
<div class="line"><a id="l02414" name="l02414"></a><span class="lineno"> 2414</span><span class="comment">         *</span></div>
<div class="line"><a id="l02415" name="l02415"></a><span class="lineno"> 2415</span><span class="comment">         * We could arrange something where we fire the on-unexpected-response handler locally and</span></div>
<div class="line"><a id="l02416" name="l02416"></a><span class="lineno"> 2416</span><span class="comment">         * send internal message to opposing guy, so they can fire their on-remote-unexpected-response handler/</span></div>
<div class="line"><a id="l02417" name="l02417"></a><span class="lineno"> 2417</span><span class="comment">         * It would require more API for m_sync_io and interacting with it though.  Thing is, before sync_io</span></div>
<div class="line"><a id="l02418" name="l02418"></a><span class="lineno"> 2418</span><span class="comment">         * pattern existed, this Channel was monolithic and could more easily do it by itself</span></div>
<div class="line"><a id="l02419" name="l02419"></a><span class="lineno"> 2419</span><span class="comment">         * (everything else was collectively more complicated but I digress).  So it did do it.  So this is a small</span></div>
<div class="line"><a id="l02420" name="l02420"></a><span class="lineno"> 2420</span><span class="comment">         * regression from that.  We could un-regress it with extra work.  At the moment we just drop the too-late</span></div>
<div class="line"><a id="l02421" name="l02421"></a><span class="lineno"> 2421</span><span class="comment">         * response.  At least the in-message details from m_sync_io would be TRACE/DATA-logged already. */</span></div>
<div class="line"><a id="l02422" name="l02422"></a><span class="lineno"> 2422</span> </div>
<div class="line"><a id="l02423" name="l02423"></a><span class="lineno"> 2423</span>        FLOW_LOG_WARNING(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *this &lt;&lt; <span class="stringliteral">&quot;]: Received response to sync-request &quot;</span></div>
<div class="line"><a id="l02424" name="l02424"></a><span class="lineno"> 2424</span>                         <span class="stringliteral">&quot;(ID [&quot;</span> &lt;&lt; id &lt;&lt; <span class="stringliteral">&quot;]) which is expecting the sync-request &quot;</span></div>
<div class="line"><a id="l02425" name="l02425"></a><span class="lineno"> 2425</span>                         <span class="stringliteral">&quot;response; however that sync-request has timed out already (or somehow an error was &quot;</span></div>
<div class="line"><a id="l02426" name="l02426"></a><span class="lineno"> 2426</span>                         <span class="stringliteral">&quot;detected in incoming-direction processing previously).  Assuming timeout: This is an &quot;</span></div>
<div class="line"><a id="l02427" name="l02427"></a><span class="lineno"> 2427</span>                         <span class="stringliteral">&quot;error on the user&#39;s part and thus not fatal.  We ignore the response.  Its details &quot;</span></div>
<div class="line"><a id="l02428" name="l02428"></a><span class="lineno"> 2428</span>                         <span class="stringliteral">&quot;should be logged (TRACE/DATA) above.  The ongoing sync-request has ID (0 if N/A): &quot;</span></div>
<div class="line"><a id="l02429" name="l02429"></a><span class="lineno"> 2429</span>                         <span class="stringliteral">&quot;[&quot;</span> &lt;&lt; (m_sync_op_state ? m_sync_op_state-&gt;m_id : 0) &lt;&lt; <span class="stringliteral">&quot;].&quot;</span>);</div>
<div class="line"><a id="l02430" name="l02430"></a><span class="lineno"> 2430</span>        return;</div>
<div class="line"><a id="l02431" name="l02431"></a><span class="lineno"> 2431</span>      }</div>
<div class="line"><a id="l02432" name="l02432"></a><span class="lineno"> 2432</span>      <span class="comment">// else: Yay, they&#39;re expecting this; let&#39;s give it to &#39;em and tickle them to wake up.</span></div>
<div class="line"><a id="l02433" name="l02433"></a><span class="lineno"> 2433</span> </div>
<div class="line"><a id="l02434" name="l02434"></a><span class="lineno"> 2434</span>      assert(holds_alternative&lt;monostate&gt;(m_sync_op_state-&gt;m_result_if_any)</div>
<div class="line"><a id="l02435" name="l02435"></a><span class="lineno"> 2435</span>             &amp;&amp; <span class="stringliteral">&quot;Only we can set the result, unless an error occurred, but we eliminated that above.&quot;</span>);</div>
<div class="line"><a id="l02436" name="l02436"></a><span class="lineno"> 2436</span> </div>
<div class="line"><a id="l02437" name="l02437"></a><span class="lineno"> 2437</span>      m_sync_op_state-&gt;m_result_if_any = Request_result{ std::move(msg_in) };</div>
<div class="line"><a id="l02438" name="l02438"></a><span class="lineno"> 2438</span> </div>
<div class="line"><a id="l02439" name="l02439"></a><span class="lineno"> 2439</span>      <span class="comment">/* All that&#39;s left is to wake up the future.wait_for() that&#39;s waiting on op_done_signal.  They might be</span></div>
<div class="line"><a id="l02440" name="l02440"></a><span class="lineno"> 2440</span><span class="comment">       * (unlikely but possible) waking right now anyway.   */</span></div>
<div class="line"><a id="l02441" name="l02441"></a><span class="lineno"> 2441</span>      m_sync_op_state-&gt;m_op_done_signal.set_value();</div>
<div class="line"><a id="l02442" name="l02442"></a><span class="lineno"> 2442</span>    }, err_code); <span class="comment">// send_tried = m_sync_io.async_request()</span></div>
<div class="line"><a id="l02443" name="l02443"></a><span class="lineno"> 2443</span> </div>
<div class="line"><a id="l02444" name="l02444"></a><span class="lineno"> 2444</span>    <span class="keywordflow">if</span> ((!send_tried) || (*err_code))</div>
<div class="line"><a id="l02445" name="l02445"></a><span class="lineno"> 2445</span>    {</div>
<div class="line"><a id="l02446" name="l02446"></a><span class="lineno"> 2446</span>      <span class="comment">// .async_request() logged enough.</span></div>
<div class="line"><a id="l02447" name="l02447"></a><span class="lineno"> 2447</span> </div>
<div class="line"><a id="l02448" name="l02448"></a><span class="lineno"> 2448</span>      <span class="comment">// The nb-send failed for whatever reason; clean this up (though this state is irrelevant but just for neatness).</span></div>
<div class="line"><a id="l02449" name="l02449"></a><span class="lineno"> 2449</span>      m_sync_op_state.reset();</div>
<div class="line"><a id="l02450" name="l02450"></a><span class="lineno"> 2450</span> </div>
<div class="line"><a id="l02451" name="l02451"></a><span class="lineno"> 2451</span>      <span class="keywordflow">if</span> (!send_tried)</div>
<div class="line"><a id="l02452" name="l02452"></a><span class="lineno"> 2452</span>      {</div>
<div class="line"><a id="l02453" name="l02453"></a><span class="lineno"> 2453</span>        <span class="comment">/* Technically m_sync_io.async_request() need not touch err_code, if it returned `false` (never tried</span></div>
<div class="line"><a id="l02454" name="l02454"></a><span class="lineno"> 2454</span><span class="comment">         * to actually send). Our contract however specifically says null return + success *err_code =</span></div>
<div class="line"><a id="l02455" name="l02455"></a><span class="lineno"> 2455</span><span class="comment">         * similar to async_request()==false. */</span></div>
<div class="line"><a id="l02456" name="l02456"></a><span class="lineno"> 2456</span>        err_code-&gt;clear();</div>
<div class="line"><a id="l02457" name="l02457"></a><span class="lineno"> 2457</span>      }</div>
<div class="line"><a id="l02458" name="l02458"></a><span class="lineno"> 2458</span>      <span class="comment">// else { *err_code is truthy. }</span></div>
<div class="line"><a id="l02459" name="l02459"></a><span class="lineno"> 2459</span> </div>
<div class="line"><a id="l02460" name="l02460"></a><span class="lineno"> 2460</span>      <span class="keywordflow">return</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a>();</div>
<div class="line"><a id="l02461" name="l02461"></a><span class="lineno"> 2461</span>    } <span class="comment">// if ((!send_tried) || (*err_code))</span></div>
<div class="line"><a id="l02462" name="l02462"></a><span class="lineno"> 2462</span>    <span class="comment">// else: m_sync_io.async_request() succeeded -- we&#39;re off to the races.</span></div>
<div class="line"><a id="l02463" name="l02463"></a><span class="lineno"> 2463</span>  } <span class="comment">// Lock_guard lock(m_mutex); // We promised in doc header to not block concurrent non-blocking calls!</span></div>
<div class="line"><a id="l02464" name="l02464"></a><span class="lineno"> 2464</span> </div>
<div class="line"><a id="l02465" name="l02465"></a><span class="lineno"> 2465</span>  <span class="keyword">const</span> <span class="keywordtype">bool</span> no_timeout = timeout == Fine_duration::max();</div>
<div class="line"><a id="l02466" name="l02466"></a><span class="lineno"> 2466</span>  <span class="keywordflow">if</span> (no_timeout)</div>
<div class="line"><a id="l02467" name="l02467"></a><span class="lineno"> 2467</span>  {</div>
<div class="line"><a id="l02468" name="l02468"></a><span class="lineno"> 2468</span>    FLOW_LOG_TRACE(<span class="stringliteral">&quot;Structured channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: &quot;</span></div>
<div class="line"><a id="l02469" name="l02469"></a><span class="lineno"> 2469</span>                   <span class="stringliteral">&quot;Sync-request (no timeout): The nb-send succeeded; &quot;</span></div>
<div class="line"><a id="l02470" name="l02470"></a><span class="lineno"> 2470</span>                   <span class="stringliteral">&quot;now we await either error or successful response receipt; sync-op ID = &quot;</span></div>
<div class="line"><a id="l02471" name="l02471"></a><span class="lineno"> 2471</span>                   <span class="stringliteral">&quot;[&quot;</span> &lt;&lt; <span class="keywordtype">id</span> &lt;&lt; <span class="stringliteral">&quot;].&quot;</span>);</div>
<div class="line"><a id="l02472" name="l02472"></a><span class="lineno"> 2472</span> </div>
<div class="line"><a id="l02473" name="l02473"></a><span class="lineno"> 2473</span>  }</div>
<div class="line"><a id="l02474" name="l02474"></a><span class="lineno"> 2474</span>  <span class="keywordflow">else</span></div>
<div class="line"><a id="l02475" name="l02475"></a><span class="lineno"> 2475</span>  {</div>
<div class="line"><a id="l02476" name="l02476"></a><span class="lineno"> 2476</span>    FLOW_LOG_TRACE(<span class="stringliteral">&quot;Structured channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: &quot;</span></div>
<div class="line"><a id="l02477" name="l02477"></a><span class="lineno"> 2477</span>                   <span class="stringliteral">&quot;Sync-request with timeout [&quot;</span> &lt;&lt; round&lt;milliseconds&gt;(timeout) &lt;&lt; <span class="stringliteral">&quot;]: The nb-send succeeded; &quot;</span></div>
<div class="line"><a id="l02478" name="l02478"></a><span class="lineno"> 2478</span>                   <span class="stringliteral">&quot;now we await either timeout or error or successful response receipt; sync-op ID = &quot;</span></div>
<div class="line"><a id="l02479" name="l02479"></a><span class="lineno"> 2479</span>                   <span class="stringliteral">&quot;[&quot;</span> &lt;&lt; <span class="keywordtype">id</span> &lt;&lt; <span class="stringliteral">&quot;].&quot;</span>);</div>
<div class="line"><a id="l02480" name="l02480"></a><span class="lineno"> 2480</span>  }</div>
<div class="line"><a id="l02481" name="l02481"></a><span class="lineno"> 2481</span> </div>
<div class="line"><a id="l02482" name="l02482"></a><span class="lineno"> 2482</span>  <span class="comment">/* Now sleep until either m_op_done_signal is tickled by thread W, or the timeout passes.</span></div>
<div class="line"><a id="l02483" name="l02483"></a><span class="lineno"> 2483</span><span class="comment">   * Note that we don&#39;t, per-se, care for which of those reasons the sleep ends, because the `promise` is</span></div>
<div class="line"><a id="l02484" name="l02484"></a><span class="lineno"> 2484</span><span class="comment">   * no more than a signal to wake us, if we don&#39;t wake first: What matters is the result in</span></div>
<div class="line"><a id="l02485" name="l02485"></a><span class="lineno"> 2485</span><span class="comment">   * m_sync_op_state by the time we lock m_mutex just below.  It is even possible, albeit unlikely,</span></div>
<div class="line"><a id="l02486" name="l02486"></a><span class="lineno"> 2486</span><span class="comment">   * that we wake up due to the timeout, yet between now and just below thread W loads a result</span></div>
<div class="line"><a id="l02487" name="l02487"></a><span class="lineno"> 2487</span><span class="comment">   * into m_sync_op_state after all.  In that case we might as well &quot;forgive&quot; the timeout and still use the</span></div>
<div class="line"><a id="l02488" name="l02488"></a><span class="lineno"> 2488</span><span class="comment">   * result.  So that&#39;s why we ignore the return value of the .wait_for().</span></div>
<div class="line"><a id="l02489" name="l02489"></a><span class="lineno"> 2489</span><span class="comment">   *</span></div>
<div class="line"><a id="l02490" name="l02490"></a><span class="lineno"> 2490</span><span class="comment">   * Also we use wait() if specifically asked to not be subject to timeout.  The rationale for this semantic,</span></div>
<div class="line"><a id="l02491" name="l02491"></a><span class="lineno"> 2491</span><span class="comment">   * rather than just passing a very high value to wait_for(), is given in our doc header (`timeout` arg).</span></div>
<div class="line"><a id="l02492" name="l02492"></a><span class="lineno"> 2492</span><span class="comment">   * TL;DR: wait_for() barfs on on very high `Fine_duration`s due to Linux pthread_timed_condwait() subtleties. */</span></div>
<div class="line"><a id="l02493" name="l02493"></a><span class="lineno"> 2493</span>  <span class="keywordflow">if</span> (no_timeout)</div>
<div class="line"><a id="l02494" name="l02494"></a><span class="lineno"> 2494</span>  {</div>
<div class="line"><a id="l02495" name="l02495"></a><span class="lineno"> 2495</span>    done_future.wait();</div>
<div class="line"><a id="l02496" name="l02496"></a><span class="lineno"> 2496</span>  }</div>
<div class="line"><a id="l02497" name="l02497"></a><span class="lineno"> 2497</span>  <span class="keywordflow">else</span></div>
<div class="line"><a id="l02498" name="l02498"></a><span class="lineno"> 2498</span>  {</div>
<div class="line"><a id="l02499" name="l02499"></a><span class="lineno"> 2499</span>    done_future.wait_for(timeout);</div>
<div class="line"><a id="l02500" name="l02500"></a><span class="lineno"> 2500</span>  }</div>
<div class="line"><a id="l02501" name="l02501"></a><span class="lineno"> 2501</span> </div>
<div class="line"><a id="l02502" name="l02502"></a><span class="lineno"> 2502</span>  <span class="comment">// The sleep ended either due to tickling of promise or timeout; scan the result once we lock mutex.</span></div>
<div class="line"><a id="l02503" name="l02503"></a><span class="lineno"> 2503</span> </div>
<div class="line"><a id="l02504" name="l02504"></a><span class="lineno"> 2504</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02505" name="l02505"></a><span class="lineno"> 2505</span> </div>
<div class="line"><a id="l02506" name="l02506"></a><span class="lineno"> 2506</span>  assert(m_sync_op_state</div>
<div class="line"><a id="l02507" name="l02507"></a><span class="lineno"> 2507</span>         &amp;&amp; <span class="stringliteral">&quot;Only this method itself can synchronously nullify m_sync_op_state.&quot;</span>);</div>
<div class="line"><a id="l02508" name="l02508"></a><span class="lineno"> 2508</span>  <span class="keyword">auto</span>&amp; result = m_sync_op_state-&gt;m_result_if_any;</div>
<div class="line"><a id="l02509" name="l02509"></a><span class="lineno"> 2509</span> </div>
<div class="line"><a id="l02510" name="l02510"></a><span class="lineno"> 2510</span>  <span class="keywordflow">if</span> (holds_alternative&lt;monostate&gt;(result))</div>
<div class="line"><a id="l02511" name="l02511"></a><span class="lineno"> 2511</span>  {</div>
<div class="line"><a id="l02512" name="l02512"></a><span class="lineno"> 2512</span>    FLOW_LOG_WARNING(<span class="stringliteral">&quot;Structured channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: &quot;</span></div>
<div class="line"><a id="l02513" name="l02513"></a><span class="lineno"> 2513</span>                     <span class="stringliteral">&quot;Sync-request: The nb-send succeeded; &quot;</span></div>
<div class="line"><a id="l02514" name="l02514"></a><span class="lineno"> 2514</span>                     <span class="stringliteral">&quot;but no response arrived in time; reporting timeout to user synchronously.&quot;</span>);</div>
<div class="line"><a id="l02515" name="l02515"></a><span class="lineno"> 2515</span> </div>
<div class="line"><a id="l02516" name="l02516"></a><span class="lineno"> 2516</span>    *err_code = <a class="code hl_enumvalue" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297abcfca4c2347f9d377dd2ac41c41dc027">transport::error::Code::S_TIMEOUT</a>;</div>
<div class="line"><a id="l02517" name="l02517"></a><span class="lineno"> 2517</span> </div>
<div class="line"><a id="l02518" name="l02518"></a><span class="lineno"> 2518</span>    m_sync_op_state.reset();</div>
<div class="line"><a id="l02519" name="l02519"></a><span class="lineno"> 2519</span>    <span class="keywordflow">return</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a>();</div>
<div class="line"><a id="l02520" name="l02520"></a><span class="lineno"> 2520</span>  }</div>
<div class="line"><a id="l02521" name="l02521"></a><span class="lineno"> 2521</span>  <span class="comment">// else</span></div>
<div class="line"><a id="l02522" name="l02522"></a><span class="lineno"> 2522</span>  <span class="keywordflow">if</span> (holds_alternative&lt;Error_code&gt;(result))</div>
<div class="line"><a id="l02523" name="l02523"></a><span class="lineno"> 2523</span>  {</div>
<div class="line"><a id="l02524" name="l02524"></a><span class="lineno"> 2524</span>    <span class="comment">// m_sync_io.async_request() did succeed.  But the sync-op failed:</span></div>
<div class="line"><a id="l02525" name="l02525"></a><span class="lineno"> 2525</span>    *err_code = get&lt;Error_code&gt;(result);</div>
<div class="line"><a id="l02526" name="l02526"></a><span class="lineno"> 2526</span> </div>
<div class="line"><a id="l02527" name="l02527"></a><span class="lineno"> 2527</span>    FLOW_LOG_WARNING(<span class="stringliteral">&quot;Structured channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: &quot;</span></div>
<div class="line"><a id="l02528" name="l02528"></a><span class="lineno"> 2528</span>                     <span class="stringliteral">&quot;Sync-request (id [&quot;</span> &lt;&lt; <span class="keywordtype">id</span> &lt;&lt; <span class="stringliteral">&quot;]): The nb-send succeeded; &quot;</span></div>
<div class="line"><a id="l02529" name="l02529"></a><span class="lineno"> 2529</span>                     <span class="stringliteral">&quot;and the sync-request finished in time; but the result was pipe-hosing error &quot;</span></div>
<div class="line"><a id="l02530" name="l02530"></a><span class="lineno"> 2530</span>                     <span class="stringliteral">&quot;[&quot;</span> &lt;&lt; *err_code &lt;&lt; <span class="stringliteral">&quot;] [&quot;</span> &lt;&lt; err_code-&gt;message() &lt;&lt; <span class="stringliteral">&quot;]; reporting this result to user &quot;</span></div>
<div class="line"><a id="l02531" name="l02531"></a><span class="lineno"> 2531</span>                     <span class="stringliteral">&quot;synchronously.&quot;</span>);</div>
<div class="line"><a id="l02532" name="l02532"></a><span class="lineno"> 2532</span> </div>
<div class="line"><a id="l02533" name="l02533"></a><span class="lineno"> 2533</span>    m_sync_op_state.reset();</div>
<div class="line"><a id="l02534" name="l02534"></a><span class="lineno"> 2534</span>    <span class="keywordflow">return</span> <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a>();</div>
<div class="line"><a id="l02535" name="l02535"></a><span class="lineno"> 2535</span>  }</div>
<div class="line"><a id="l02536" name="l02536"></a><span class="lineno"> 2536</span>  <span class="comment">// else</span></div>
<div class="line"><a id="l02537" name="l02537"></a><span class="lineno"> 2537</span> </div>
<div class="line"><a id="l02538" name="l02538"></a><span class="lineno"> 2538</span>  assert(holds_alternative&lt;Request_result&gt;(result));</div>
<div class="line"><a id="l02539" name="l02539"></a><span class="lineno"> 2539</span> </div>
<div class="line"><a id="l02540" name="l02540"></a><span class="lineno"> 2540</span>  FLOW_LOG_TRACE(<span class="stringliteral">&quot;Structured channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: &quot;</span></div>
<div class="line"><a id="l02541" name="l02541"></a><span class="lineno"> 2541</span>                 <span class="stringliteral">&quot;Sync-request (id [&quot;</span> &lt;&lt; <span class="keywordtype">id</span> &lt;&lt; <span class="stringliteral">&quot;]): The nb-send succeeded; &quot;</span></div>
<div class="line"><a id="l02542" name="l02542"></a><span class="lineno"> 2542</span>                 <span class="stringliteral">&quot;and the sync-request finished in time with response having been received (details above); &quot;</span></div>
<div class="line"><a id="l02543" name="l02543"></a><span class="lineno"> 2543</span>                 <span class="stringliteral">&quot;reporting this result to user synchronously.&quot;</span>);</div>
<div class="line"><a id="l02544" name="l02544"></a><span class="lineno"> 2544</span> </div>
<div class="line"><a id="l02545" name="l02545"></a><span class="lineno"> 2545</span>  <span class="keyword">const</span> <span class="keyword">auto</span> rsp = std::move(get&lt;Request_result&gt;(result).m_rsp);</div>
<div class="line"><a id="l02546" name="l02546"></a><span class="lineno"> 2546</span>  <span class="comment">// Might as well move --^-- the shared_ptr outta there for perf.</span></div>
<div class="line"><a id="l02547" name="l02547"></a><span class="lineno"> 2547</span> </div>
<div class="line"><a id="l02548" name="l02548"></a><span class="lineno"> 2548</span>  m_sync_op_state.reset();</div>
<div class="line"><a id="l02549" name="l02549"></a><span class="lineno"> 2549</span> </div>
<div class="line"><a id="l02550" name="l02550"></a><span class="lineno"> 2550</span>  assert(!*err_code);</div>
<div class="line"><a id="l02551" name="l02551"></a><span class="lineno"> 2551</span>  <span class="keywordflow">return</span> rsp;</div>
<div class="line"><a id="l02552" name="l02552"></a><span class="lineno"> 2552</span>} <span class="comment">// Channel::sync_request()</span></div>
<div class="line"><a id="l02553" name="l02553"></a><span class="lineno"> 2553</span> </div>
<div class="line"><a id="l02554" name="l02554"></a><span class="lineno"> 2554</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02555" name="l02555"></a><span class="lineno"> 2555</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_unexpected_response_handler&gt;</div>
<div class="line"><a id="l02556" name="l02556"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ab7cd0bed6392cb155f9ee21071c5226b"> 2556</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::set_unexpected_response_handler(On_unexpected_response_handler&amp;&amp; on_func)</div>
<div class="line"><a id="l02557" name="l02557"></a><span class="lineno"> 2557</span>{</div>
<div class="line"><a id="l02558" name="l02558"></a><span class="lineno"> 2558</span>  <span class="comment">/* We are in thread U; or thread W (if invoked from a user handler); always serially.</span></div>
<div class="line"><a id="l02559" name="l02559"></a><span class="lineno"> 2559</span><span class="comment">   * Nothing is locked either way due to how we actually invoke user-supplied handlers. */</span></div>
<div class="line"><a id="l02560" name="l02560"></a><span class="lineno"> 2560</span> </div>
<div class="line"><a id="l02561" name="l02561"></a><span class="lineno"> 2561</span>  <span class="keyword">auto</span> real_on_func = [<span class="keyword">this</span>, on_func = std::move(on_func)](<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">Msg_in_ptr</a>&amp;&amp; msg_in) <span class="keyword">mutable</span></div>
<div class="line"><a id="l02562" name="l02562"></a><span class="lineno"> 2562</span>  {</div>
<div class="line"><a id="l02563" name="l02563"></a><span class="lineno"> 2563</span>    <span class="comment">// We are in thread W.  m_mutex is locked!</span></div>
<div class="line"><a id="l02564" name="l02564"></a><span class="lineno"> 2564</span> </div>
<div class="line"><a id="l02565" name="l02565"></a><span class="lineno"> 2565</span>    <span class="comment">/* *Please* see comment in expect_msg_impl() similar spot regarding why we post() here.</span></div>
<div class="line"><a id="l02566" name="l02566"></a><span class="lineno"> 2566</span><span class="comment">     *</span></div>
<div class="line"><a id="l02567" name="l02567"></a><span class="lineno"> 2567</span><span class="comment">     * Orthogonally: We don&#39;t use the shared_ptr&lt;&gt; trick to avoid copying on_func.  We could, but it doesn&#39;t</span></div>
<div class="line"><a id="l02568" name="l02568"></a><span class="lineno"> 2568</span><span class="comment">     * seem perf-critical, given that it&#39;s an unexpected-response handler -- doubt people will be having these</span></div>
<div class="line"><a id="l02569" name="l02569"></a><span class="lineno"> 2569</span><span class="comment">     * fire constantly.  @todo Probably should still though do it though.  It&#39;s a few lines (see expect_msg*()). */</span></div>
<div class="line"><a id="l02570" name="l02570"></a><span class="lineno"> 2570</span>    m_worker.post([<span class="keyword">this</span>, on_func, msg_in = std::move(msg_in)]() <span class="keyword">mutable</span></div>
<div class="line"><a id="l02571" name="l02571"></a><span class="lineno"> 2571</span>    {</div>
<div class="line"><a id="l02572" name="l02572"></a><span class="lineno"> 2572</span>      <span class="comment">// We are in thread W.  Nothing is locked.</span></div>
<div class="line"><a id="l02573" name="l02573"></a><span class="lineno"> 2573</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Invoking user on-unexpected-rsp handler.&quot;</span>);</div>
<div class="line"><a id="l02574" name="l02574"></a><span class="lineno"> 2574</span>      on_func(std::move(msg_in));</div>
<div class="line"><a id="l02575" name="l02575"></a><span class="lineno"> 2575</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;Handler completed.&quot;</span>);</div>
<div class="line"><a id="l02576" name="l02576"></a><span class="lineno"> 2576</span>    });</div>
<div class="line"><a id="l02577" name="l02577"></a><span class="lineno"> 2577</span>  };</div>
<div class="line"><a id="l02578" name="l02578"></a><span class="lineno"> 2578</span> </div>
<div class="line"><a id="l02579" name="l02579"></a><span class="lineno"> 2579</span>  <span class="comment">// Reminder: we must protect against concurrent calls from user threads U1, U2, ...; and against access from W.</span></div>
<div class="line"><a id="l02580" name="l02580"></a><span class="lineno"> 2580</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02581" name="l02581"></a><span class="lineno"> 2581</span>  <span class="keywordflow">return</span> m_sync_io.set_unexpected_response_handler(std::move(real_on_func));</div>
<div class="line"><a id="l02582" name="l02582"></a><span class="lineno"> 2582</span>} <span class="comment">// Channel::set_unexpected_response_handler()</span></div>
<div class="line"><a id="l02583" name="l02583"></a><span class="lineno"> 2583</span> </div>
<div class="line"><a id="l02584" name="l02584"></a><span class="lineno"> 2584</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02585" name="l02585"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#ad3070c369762b2f5e85555155f65bdaa"> 2585</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::unset_unexpected_response_handler()</div>
<div class="line"><a id="l02586" name="l02586"></a><span class="lineno"> 2586</span>{</div>
<div class="line"><a id="l02587" name="l02587"></a><span class="lineno"> 2587</span>  <span class="comment">// Reminder: we must protect against concurrent calls from user threads U1, U2, ...; and against access from W.</span></div>
<div class="line"><a id="l02588" name="l02588"></a><span class="lineno"> 2588</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02589" name="l02589"></a><span class="lineno"> 2589</span>  <span class="keywordflow">return</span> m_sync_io.unset_unexpected_response_handler();</div>
<div class="line"><a id="l02590" name="l02590"></a><span class="lineno"> 2590</span>}</div>
<div class="line"><a id="l02591" name="l02591"></a><span class="lineno"> 2591</span> </div>
<div class="line"><a id="l02592" name="l02592"></a><span class="lineno"> 2592</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02593" name="l02593"></a><span class="lineno"> 2593</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> On_remote_unexpected_response_handler&gt;</div>
<div class="line"><a id="l02594" name="l02594"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a9ec7ff431b51fec8aacacccb23a2d4e3"> 2594</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::set_remote_unexpected_response_handler(On_remote_unexpected_response_handler&amp;&amp; on_func)</div>
<div class="line"><a id="l02595" name="l02595"></a><span class="lineno"> 2595</span>{</div>
<div class="line"><a id="l02596" name="l02596"></a><span class="lineno"> 2596</span>  <span class="keyword">using </span>std::string;</div>
<div class="line"><a id="l02597" name="l02597"></a><span class="lineno"> 2597</span> </div>
<div class="line"><a id="l02598" name="l02598"></a><span class="lineno"> 2598</span>  <span class="comment">/* We are in thread U; or thread W (if invoked from a user handler); always serially.</span></div>
<div class="line"><a id="l02599" name="l02599"></a><span class="lineno"> 2599</span><span class="comment">   * Nothing is locked either way due to how we actually invoke user-supplied handlers. */</span></div>
<div class="line"><a id="l02600" name="l02600"></a><span class="lineno"> 2600</span> </div>
<div class="line"><a id="l02601" name="l02601"></a><span class="lineno"> 2601</span>  <span class="keyword">auto</span> real_on_func = [<span class="keyword">this</span>, on_func = std::move(on_func)]</div>
<div class="line"><a id="l02602" name="l02602"></a><span class="lineno"> 2602</span>                        (<a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#a4d4995b27b7a6944fbcceee7657f6413">msg_id_out_t</a> msg_id_out, <span class="keywordtype">string</span>&amp;&amp; msg_metadata_text) <span class="keyword">mutable</span></div>
<div class="line"><a id="l02603" name="l02603"></a><span class="lineno"> 2603</span>  {</div>
<div class="line"><a id="l02604" name="l02604"></a><span class="lineno"> 2604</span>    <span class="comment">// We are in thread W.  m_mutex is locked!</span></div>
<div class="line"><a id="l02605" name="l02605"></a><span class="lineno"> 2605</span> </div>
<div class="line"><a id="l02606" name="l02606"></a><span class="lineno"> 2606</span>    <span class="comment">/* *Please* see comment in expect_msg_impl() similar spot regarding why we post() here.</span></div>
<div class="line"><a id="l02607" name="l02607"></a><span class="lineno"> 2607</span><span class="comment">     *</span></div>
<div class="line"><a id="l02608" name="l02608"></a><span class="lineno"> 2608</span><span class="comment">     * Orthogonally: We don&#39;t use the shared_ptr&lt;&gt; trick to avoid copying on_func.  We could, but it doesn&#39;t</span></div>
<div class="line"><a id="l02609" name="l02609"></a><span class="lineno"> 2609</span><span class="comment">     * seem perf-critical, given that it&#39;s an unexpected-response handler -- doubt people will be having these</span></div>
<div class="line"><a id="l02610" name="l02610"></a><span class="lineno"> 2610</span><span class="comment">     * fire constantly.  @todo Probably should still though do it though.  It&#39;s a few lines (see expect_msg*()). */</span></div>
<div class="line"><a id="l02611" name="l02611"></a><span class="lineno"> 2611</span>    m_worker.post([<span class="keyword">this</span>, on_func, msg_id_out, msg_metadata_text = std::move(msg_metadata_text)]() <span class="keyword">mutable</span></div>
<div class="line"><a id="l02612" name="l02612"></a><span class="lineno"> 2612</span>    {</div>
<div class="line"><a id="l02613" name="l02613"></a><span class="lineno"> 2613</span>      <span class="comment">// We are in thread W.  Nothing is locked.</span></div>
<div class="line"><a id="l02614" name="l02614"></a><span class="lineno"> 2614</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;struc::Channel [&quot;</span> &lt;&lt; *<span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;]: Invoking user on-remote-unexpected-rsp handler.&quot;</span>);</div>
<div class="line"><a id="l02615" name="l02615"></a><span class="lineno"> 2615</span>      on_func(msg_id_out, std::move(msg_metadata_text));</div>
<div class="line"><a id="l02616" name="l02616"></a><span class="lineno"> 2616</span>      FLOW_LOG_TRACE(<span class="stringliteral">&quot;Handler completed.&quot;</span>);</div>
<div class="line"><a id="l02617" name="l02617"></a><span class="lineno"> 2617</span>    });</div>
<div class="line"><a id="l02618" name="l02618"></a><span class="lineno"> 2618</span>  };</div>
<div class="line"><a id="l02619" name="l02619"></a><span class="lineno"> 2619</span> </div>
<div class="line"><a id="l02620" name="l02620"></a><span class="lineno"> 2620</span>  <span class="comment">// Reminder: we must protect against concurrent calls from user threads U1, U2, ...; and against access from W.</span></div>
<div class="line"><a id="l02621" name="l02621"></a><span class="lineno"> 2621</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02622" name="l02622"></a><span class="lineno"> 2622</span>  <span class="keywordflow">return</span> m_sync_io.set_remote_unexpected_response_handler(std::move(real_on_func));</div>
<div class="line"><a id="l02623" name="l02623"></a><span class="lineno"> 2623</span>} <span class="comment">// Channel::set_remote_unexpected_response_handler()</span></div>
<div class="line"><a id="l02624" name="l02624"></a><span class="lineno"> 2624</span> </div>
<div class="line"><a id="l02625" name="l02625"></a><span class="lineno"> 2625</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02626" name="l02626"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a1d5415ad72e5758f15fd49d2faabb3e0"> 2626</a></span><span class="keywordtype">bool</span> CLASS_STRUCTURED_CHANNEL::unset_remote_unexpected_response_handler()</div>
<div class="line"><a id="l02627" name="l02627"></a><span class="lineno"> 2627</span>{</div>
<div class="line"><a id="l02628" name="l02628"></a><span class="lineno"> 2628</span>  <span class="comment">// Reminder: we must protect against concurrent calls from user threads U1, U2, ...; and against access from W.</span></div>
<div class="line"><a id="l02629" name="l02629"></a><span class="lineno"> 2629</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02630" name="l02630"></a><span class="lineno"> 2630</span>  <span class="keywordflow">return</span> m_sync_io.unset_remote_unexpected_response_handler();</div>
<div class="line"><a id="l02631" name="l02631"></a><span class="lineno"> 2631</span>}</div>
<div class="line"><a id="l02632" name="l02632"></a><span class="lineno"> 2632</span> </div>
<div class="line"><a id="l02633" name="l02633"></a><span class="lineno"> 2633</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02634" name="l02634"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a1d0225edcfe5f000f26787d5fa5f6821"> 2634</a></span><span class="keyword">const</span> <span class="keyword">typename</span> CLASS_STRUCTURED_CHANNEL::Owned_channel&amp; CLASS_STRUCTURED_CHANNEL::owned_channel()<span class="keyword"> const</span></div>
<div class="line"><a id="l02635" name="l02635"></a><span class="lineno"> 2635</span><span class="keyword"></span>{</div>
<div class="line"><a id="l02636" name="l02636"></a><span class="lineno"> 2636</span>  <span class="comment">// Always safe per contract.</span></div>
<div class="line"><a id="l02637" name="l02637"></a><span class="lineno"> 2637</span>  <span class="keywordflow">return</span> m_sync_io.owned_channel();</div>
<div class="line"><a id="l02638" name="l02638"></a><span class="lineno"> 2638</span>}</div>
<div class="line"><a id="l02639" name="l02639"></a><span class="lineno"> 2639</span> </div>
<div class="line"><a id="l02640" name="l02640"></a><span class="lineno"> 2640</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02641" name="l02641"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#af9130e43dc985fca4a41f19581048b51"> 2641</a></span><span class="keyword">typename</span> CLASS_STRUCTURED_CHANNEL::Owned_channel* CLASS_STRUCTURED_CHANNEL::owned_channel_mutable()</div>
<div class="line"><a id="l02642" name="l02642"></a><span class="lineno"> 2642</span>{</div>
<div class="line"><a id="l02643" name="l02643"></a><span class="lineno"> 2643</span>  <span class="comment">// Always safe per contract.</span></div>
<div class="line"><a id="l02644" name="l02644"></a><span class="lineno"> 2644</span>  <span class="keywordflow">return</span> m_sync_io.owned_channel_mutable();</div>
<div class="line"><a id="l02645" name="l02645"></a><span class="lineno"> 2645</span>}</div>
<div class="line"><a id="l02646" name="l02646"></a><span class="lineno"> 2646</span> </div>
<div class="line"><a id="l02647" name="l02647"></a><span class="lineno"> 2647</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02648" name="l02648"></a><span class="lineno"><a class="line" href="classipc_1_1transport_1_1struc_1_1Channel.html#a9a540a274df3bc7da8fc35ed2a2c1e57"> 2648</a></span><span class="keyword">const</span> <a class="code hl_typedef" href="namespaceipc_1_1transport_1_1struc.html#a6751c05fb6582a34c7c47ac470c4a48b">Session_token</a>&amp; CLASS_STRUCTURED_CHANNEL::session_token()<span class="keyword"> const</span></div>
<div class="line"><a id="l02649" name="l02649"></a><span class="lineno"> 2649</span><span class="keyword"></span>{</div>
<div class="line"><a id="l02650" name="l02650"></a><span class="lineno"> 2650</span>  <span class="comment">// Gotta lock per contract (can change during log-in processing in thread W).</span></div>
<div class="line"><a id="l02651" name="l02651"></a><span class="lineno"> 2651</span>  <a class="code hl_typedef" href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">Lock_guard</a> lock(m_mutex);</div>
<div class="line"><a id="l02652" name="l02652"></a><span class="lineno"> 2652</span>  <span class="keywordflow">return</span> m_sync_io.session_token();</div>
<div class="line"><a id="l02653" name="l02653"></a><span class="lineno"> 2653</span>}</div>
<div class="line"><a id="l02654" name="l02654"></a><span class="lineno"> 2654</span><span class="comment"></span> </div>
<div class="line"><a id="l02655" name="l02655"></a><span class="lineno"> 2655</span><span class="comment">/// @cond</span></div>
<div class="line"><a id="l02656" name="l02656"></a><span class="lineno"> 2656</span><span class="comment"></span><span class="comment">// -^- Doxygen, please ignore the following.  It gets confused by something here and gives warnings.</span></div>
<div class="line"><a id="l02657" name="l02657"></a><span class="lineno"> 2657</span> </div>
<div class="line"><a id="l02658" name="l02658"></a><span class="lineno"> 2658</span><a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div>
<div class="line"><a id="l02659" name="l02659"></a><span class="lineno"> 2659</span>std::ostream&amp; <a class="code hl_function" href="namespaceipc_1_1transport_1_1struc.html#ae272f248d74db0486c4d9411715db15d">operator&lt;&lt;</a>(std::ostream&amp; os, <span class="keyword">const</span> <a class="code hl_define" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a5313383b4bb7158e2f65d89690348f04">CLASS_STRUCTURED_CHANNEL</a>&amp; val)</div>
<div class="line"><a id="l02660" name="l02660"></a><span class="lineno"> 2660</span>{</div>
<div class="line"><a id="l02661" name="l02661"></a><span class="lineno"> 2661</span>  <span class="comment">/* For now mirroring what Sync_io_obj does.  So our &amp;val is output but the main useful info (owned_channel [])</span></div>
<div class="line"><a id="l02662" name="l02662"></a><span class="lineno"> 2662</span><span class="comment">   * is still visible.  Could instead output &amp;val and val.m_sync_io would show owned_channel[] and whatever</span></div>
<div class="line"><a id="l02663" name="l02663"></a><span class="lineno"> 2663</span><span class="comment">   * else it wanted to.  It&#39;s just bulky that way, with 2 `this` addresses.  Look, whatever! */</span></div>
<div class="line"><a id="l02664" name="l02664"></a><span class="lineno"> 2664</span>  <span class="keywordflow">return</span> os &lt;&lt; <span class="stringliteral">&quot;[owned_channel [&quot;</span> &lt;&lt; val.owned_channel() &lt;&lt; <span class="stringliteral">&quot;]]@&quot;</span> &lt;&lt; <span class="keyword">static_cast&lt;</span><span class="keyword">const </span><span class="keywordtype">void</span>*<span class="keyword">&gt;</span>(&amp;val);</div>
<div class="line"><a id="l02665" name="l02665"></a><span class="lineno"> 2665</span>}</div>
<div class="line"><a id="l02666" name="l02666"></a><span class="lineno"> 2666</span> </div>
<div class="line"><a id="l02667" name="l02667"></a><span class="lineno"> 2667</span><span class="comment">// -v- Doxygen, please stop ignoring.</span><span class="comment"></span></div>
<div class="line"><a id="l02668" name="l02668"></a><span class="lineno"> 2668</span><span class="comment">/// @endcond</span></div>
<div class="line"><a id="l02669" name="l02669"></a><span class="lineno"> 2669</span><span class="comment"></span> </div>
<div class="line"><a id="l02670" name="l02670"></a><span class="lineno"> 2670</span><span class="preprocessor">#undef CLASS_STRUCTURED_CHANNEL</span></div>
<div class="line"><a id="l02671" name="l02671"></a><span class="lineno"> 2671</span><span class="preprocessor">#undef TEMPLATE_STRUCTURED_CHANNEL</span></div>
<div class="line"><a id="l02672" name="l02672"></a><span class="lineno"> 2672</span> </div>
<div class="line"><a id="l02673" name="l02673"></a><span class="lineno"> 2673</span>} <span class="comment">// namespace ipc::transport::struc</span></div>
<div class="ttc" id="aclassipc_1_1transport_1_1Null__peer_html"><div class="ttname"><a href="classipc_1_1transport_1_1Null__peer.html">ipc::transport::Null_peer</a></div><div class="ttdoc">Dummy type for use as a template param to Channel when either the blobs pipe or handles pipe is disab...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__core_2src_2ipc_2transport_2channel_8hpp_source.html#l00999">channel.hpp:1000</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html">ipc::transport::struc::Channel</a></div><div class="ttdoc">Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00580">channel.hpp:583</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a0054bbf18bc769b2a5b95f249e672c0a"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a0054bbf18bc769b2a5b95f249e672c0a">ipc::transport::struc::Channel::expect_log_in_request</a></div><div class="ttdeci">bool expect_log_in_request(Msg_which_in which, On_msg_handler &amp;&amp;on_log_in_req_func)</div><div class="ttdoc">In log-in phase as server only: Registers the expectation of up to 1 log-in request in-message whose ...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02069">channel.hpp:2069</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a01c90903e715ebcf64d8b5ea0d114bc0"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a01c90903e715ebcf64d8b5ea0d114bc0">ipc::transport::struc::Channel::m_mutex</a></div><div class="ttdeci">Mutex m_mutex</div><div class="ttdoc">Mutex protecting the in-message/out-message state in *this.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01494">channel.hpp:1494</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a0500d7dc635203ec6c32ca4b096a96c6"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a0500d7dc635203ec6c32ca4b096a96c6">ipc::transport::struc::Channel::m_sync_op_mutex</a></div><div class="ttdeci">Mutex m_sync_op_mutex</div><div class="ttdoc">Mutex causing, specifically, any sync_request() (or similar future methods) to execute in series and ...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01450">channel.hpp:1450</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a05d1cd2fc6a81a39c50a24322fb5c165"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a05d1cd2fc6a81a39c50a24322fb5c165">ipc::transport::struc::Channel::Msg_in</a></div><div class="ttdeci">typename Sync_io_obj::Msg_in Msg_in</div><div class="ttdoc">Encapsulation of any in-message instance received by a *this of this type.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00633">channel.hpp:633</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a08062e4cc99347e94e9e917b382985ee"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a08062e4cc99347e94e9e917b382985ee">ipc::transport::struc::Channel::heap_fixed_builder_config</a></div><div class="ttdeci">static Heap_fixed_builder::Config heap_fixed_builder_config(const Owned_channel &amp;channel)</div><div class="ttdoc">Utility for use when Builder_config template param is Heap_fixed_builder::Config, this returns such a...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01979">channel.hpp:1979</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a160a8d49624f15a2596ee7b0244584b0"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a160a8d49624f15a2596ee7b0244584b0">ipc::transport::struc::Channel::expect_msg</a></div><div class="ttdeci">bool expect_msg(Msg_which_in which, On_msg_handler &amp;&amp;on_msg_func)</div><div class="ttdoc">Registers the expectation of up to 1 notification in-message whose Msg_which equals which.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02062">channel.hpp:2062</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a1d0225edcfe5f000f26787d5fa5f6821"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a1d0225edcfe5f000f26787d5fa5f6821">ipc::transport::struc::Channel::owned_channel</a></div><div class="ttdeci">const Owned_channel &amp; owned_channel() const</div><div class="ttdoc">Access to immutable transport::Channel moved-into *this at construction.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02634">channel.hpp:2634</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a1d5415ad72e5758f15fd49d2faabb3e0"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a1d5415ad72e5758f15fd49d2faabb3e0">ipc::transport::struc::Channel::unset_remote_unexpected_response_handler</a></div><div class="ttdeci">bool unset_remote_unexpected_response_handler()</div><div class="ttdoc">Undoes set_remote_unexpected_response_handler().</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02626">channel.hpp:2626</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a1df9dd26651017e61d7701bf3af42260"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a1df9dd26651017e61d7701bf3af42260">ipc::transport::struc::Channel::On_msg_func</a></div><div class="ttdeci">Function&lt; void(Msg_in_ptr &amp;&amp;msg)&gt; On_msg_func</div><div class="ttdoc">Concrete type corresponding to On_msg_handler template param: in-message handler.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01416">channel.hpp:1416</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a2184077da7828589d20d7f92a31a6394"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a2184077da7828589d20d7f92a31a6394">ipc::transport::struc::Channel::m_worker</a></div><div class="ttdeci">flow::async::Single_thread_task_loop m_worker</div><div class="ttdoc">Thread W used to (1) fire user-provided handlers and (2) perform any async work requested by m_sync_i...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01578">channel.hpp:1578</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a27a273ed7e1aca34b721fea22c869a41"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a27a273ed7e1aca34b721fea22c869a41">ipc::transport::struc::Channel::Msg_body</a></div><div class="ttdeci">typename Sync_io_obj::Msg_body Msg_body</div><div class="ttdoc">Short-hand for the Message_body template param, this is the capnp message schema transmissible over *...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00602">channel.hpp:602</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a3376b821b129ca3847484a178e080c67"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a3376b821b129ca3847484a178e080c67">ipc::transport::struc::Channel::expect_msgs</a></div><div class="ttdeci">bool expect_msgs(Msg_which_in which, On_msg_handler &amp;&amp;on_msg_func)</div><div class="ttdoc">Registers the expectation of 0+ notification in-messages whose Msg_which equals which.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02192">channel.hpp:2192</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a33b4785c212ad88d8322fcc2f4369351"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a33b4785c212ad88d8322fcc2f4369351">ipc::transport::struc::Channel::start</a></div><div class="ttdeci">bool start(Task_err &amp;&amp;on_err_func)</div><div class="ttdoc">Permanently memorizes the incoming-direction on-error handler, thus authorizing the emission of any i...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01903">channel.hpp:1903</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a346752b515926a2938ed2adb9de92b1e"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a346752b515926a2938ed2adb9de92b1e">ipc::transport::struc::Channel::Builder_config</a></div><div class="ttdeci">typename Sync_io_obj::Builder_config Builder_config</div><div class="ttdoc">Short-hand for the builder engine type.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00597">channel.hpp:597</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a34780bd3507a571cb719ce1d59e5d56f"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a34780bd3507a571cb719ce1d59e5d56f">ipc::transport::struc::Channel::undo_expect_responses</a></div><div class="ttdeci">bool undo_expect_responses(msg_id_out_t originating_msg_id)</div><div class="ttdoc">Unregisters the expectation earlier-registered with the id_unless_one_off != nullptr form of async_re...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02268">channel.hpp:2268</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a394e0f9cfa5f9bd4ba9ee17d3d54a8b3"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a394e0f9cfa5f9bd4ba9ee17d3d54a8b3">ipc::transport::struc::Channel::create_msg</a></div><div class="ttdeci">Msg_out create_msg(Native_handle &amp;&amp;hndl_or_null=Native_handle()) const</div><div class="ttdoc">Creates/returns empty out-message, optionally also holding a native handle, to mutate and later send(...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02054">channel.hpp:2054</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a4a0188052c15cab70d712f41b0e74ba7"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a4a0188052c15cab70d712f41b0e74ba7">ipc::transport::struc::Channel::Owned_channel</a></div><div class="ttdeci">typename Sync_io_obj::Owned_channel Owned_channel</div><div class="ttdoc">Short-hand for the transport::Channel type passed into ctor and returned by owned_channel().</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00594">channel.hpp:594</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a4cc597a9ff8f460f5a773005f0a05805"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a4cc597a9ff8f460f5a773005f0a05805">ipc::transport::struc::Channel::Msg_which_out</a></div><div class="ttdeci">typename Sync_io_obj::Msg_which_out Msg_which_out</div><div class="ttdoc">Stylistic nicety, indicating that a Msg_which applies to an out-message rather than an in-message.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00615">channel.hpp:615</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a4d4995b27b7a6944fbcceee7657f6413"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a4d4995b27b7a6944fbcceee7657f6413">ipc::transport::struc::Channel::msg_id_out_t</a></div><div class="ttdeci">typename Sync_io_obj::msg_id_out_t msg_id_out_t</div><div class="ttdoc">Short-hand for convenience for the same thing in non-parameterized base Channel_base.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00643">channel.hpp:643</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a5e905a57052ba370d8d2f45a361982d8"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a5e905a57052ba370d8d2f45a361982d8">ipc::transport::struc::Channel::m_snd_end_sending_on_done_func_or_empty</a></div><div class="ttdeci">flow::async::Task_asio_err m_snd_end_sending_on_done_func_or_empty</div><div class="ttdoc">Analogous to Async_adapter_sender::m_end_sending_on_done_func_or_empty.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01572">channel.hpp:1572</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a629c06957e1c5fac96d62473f7e18966"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a629c06957e1c5fac96d62473f7e18966">ipc::transport::struc::Channel::heap_reader_config</a></div><div class="ttdeci">static Heap_reader::Config heap_reader_config(const Owned_channel &amp;channel)</div><div class="ttdoc">Deserializing counterpart to heap_fixed_builder_config().</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02024">channel.hpp:2024</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a860cc99a701576879ebb5a1db58153cc"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc">ipc::transport::struc::Channel::Msg_out</a></div><div class="ttdeci">typename Sync_io_obj::Msg_out Msg_out</div><div class="ttdoc">Encapsulation of any out-message payload sent or meant to be sent via send() (et al) by a *this of th...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00624">channel.hpp:624</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a896bb326a58f433bade75b62f1893462"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a896bb326a58f433bade75b62f1893462">ipc::transport::struc::Channel::undo_expect_msgs</a></div><div class="ttdeci">bool undo_expect_msgs(Msg_which_in which)</div><div class="ttdoc">Unregisters the expectation earlier-registered with expect_msgs().</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02260">channel.hpp:2260</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a8ca2772b0a657cb55f140a6273e528b9"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a8ca2772b0a657cb55f140a6273e528b9">ipc::transport::struc::Channel::expect_msg_impl</a></div><div class="ttdeci">bool expect_msg_impl(Msg_which_in which, On_msg_handler &amp;&amp;on_msg_func)</div><div class="ttdoc">Implements the one-off expect-message APIs expect_msg() and expect_log_in_request().</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02076">channel.hpp:2076</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a969bc2021565c542c902fc14ff711c38"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a969bc2021565c542c902fc14ff711c38">ipc::transport::struc::Channel::struct_builder_config</a></div><div class="ttdeci">const Builder_config &amp; struct_builder_config() const</div><div class="ttdoc">Returns the (light-weight) Builder_config specified (directly or indirectly) at construction time.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02031">channel.hpp:2031</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a97506bcb695f22e7ca6b480bae5b2346"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a97506bcb695f22e7ca6b480bae5b2346">ipc::transport::struc::Channel::async_request</a></div><div class="ttdeci">bool async_request(const Msg_out &amp;msg, const Msg_in *originating_msg_or_null, msg_id_out_t *id_unless_one_off, On_msg_handler &amp;&amp;on_rsp_func, Error_code *err_code=0)</div><div class="ttdoc">Identical to send() sends the out-message not as a notification but as a request, registering the exp...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02292">channel.hpp:2293</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a9a0382aa663c177f2a38b576d06b251e"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a9a0382aa663c177f2a38b576d06b251e">ipc::transport::struc::Channel::Msg_which</a></div><div class="ttdeci">typename Sync_io_obj::Msg_which Msg_which</div><div class="ttdoc">Short-hand for the Message_body top-level anon capnp-union enumeration.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00609">channel.hpp:609</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a9a540a274df3bc7da8fc35ed2a2c1e57"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a9a540a274df3bc7da8fc35ed2a2c1e57">ipc::transport::struc::Channel::session_token</a></div><div class="ttdeci">const Session_token &amp; session_token() const</div><div class="ttdoc">Returns the (non-nil) logged-in session token; or nil if not in logged-in phase, or if a prior error ...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02648">channel.hpp:2648</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_a9ec7ff431b51fec8aacacccb23a2d4e3"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#a9ec7ff431b51fec8aacacccb23a2d4e3">ipc::transport::struc::Channel::set_remote_unexpected_response_handler</a></div><div class="ttdeci">bool set_remote_unexpected_response_handler(On_remote_unexpected_response_handler &amp;&amp;on_func)</div><div class="ttdoc">Registers the handler to invoke when the remote peer encounters the condition that would fire the rem...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02594">channel.hpp:2594</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_aa41aee3c76035f43833078e625e6ef78"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#aa41aee3c76035f43833078e625e6ef78">ipc::transport::struc::Channel::sync_request</a></div><div class="ttdeci">Msg_in_ptr sync_request(const Msg_out &amp;msg, const Msg_in *originating_msg_or_null=0, Error_code *err_code=0)</div><div class="ttdoc">Equivalent to the other sync_request() overload but with no timeout; meaning it shall exit only once ...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02284">channel.hpp:2284</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_ab08057edd9832d94ea0e18a17c42200a"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#ab08057edd9832d94ea0e18a17c42200a">ipc::transport::struc::Channel::async_end_sending</a></div><div class="ttdeci">bool async_end_sending(Task_err &amp;&amp;on_done_func)</div><div class="ttdoc">Operating at the unstructured layer, executes a graceful-close send by forwarding to the async transp...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01801">channel.hpp:1801</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_ab40d8133d53135bcc41a12cc27fc8e13"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#ab40d8133d53135bcc41a12cc27fc8e13">ipc::transport::struc::Channel::m_sync_op_state</a></div><div class="ttdeci">std::optional&lt; Sync_op_state &gt; m_sync_op_state</div><div class="ttdoc">The current state of the blocking sync-op mechanism; a variant that broadly describes the state as: n...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01566">channel.hpp:1566</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_ab7cd0bed6392cb155f9ee21071c5226b"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#ab7cd0bed6392cb155f9ee21071c5226b">ipc::transport::struc::Channel::set_unexpected_response_handler</a></div><div class="ttdeci">bool set_unexpected_response_handler(On_unexpected_response_handler &amp;&amp;on_func)</div><div class="ttdoc">Registers the handler to invoke when a response in-message arrives, but no response-expectation has b...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02556">channel.hpp:2556</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_abb0ed2e666191dd85e543072077bf38b"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#abb0ed2e666191dd85e543072077bf38b">ipc::transport::struc::Channel::m_sync_op_state_id</a></div><div class="ttdeci">Sync_op_state::id_t m_sync_op_state_id</div><div class="ttdoc">Next unique ID for Sync_op_state::m_id.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01569">channel.hpp:1569</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_abe73bfa20ca0207ac8aa63d26d54de83"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#abe73bfa20ca0207ac8aa63d26d54de83">ipc::transport::struc::Channel::Channel</a></div><div class="ttdeci">Channel(flow::log::Logger *logger_ptr, Channel_obj &amp;&amp;channel, Ctor_args &amp;&amp;... ctor_args)</div><div class="ttdoc">All explicit constructors: signatures match exactly those of struc::sync_io::Channel (a/k/a Sync_io_o...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01630">channel.hpp:1630</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_abf9f4ae00258efb7a5d868a087658ffe"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#abf9f4ae00258efb7a5d868a087658ffe">ipc::transport::struc::Channel::~Channel</a></div><div class="ttdeci">~Channel()</div><div class="ttdoc">Invokes the destructor on the Owned_channel.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01705">channel.hpp:1705</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_ac2a3a80151886bec41f3fc3a8880e384"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384">ipc::transport::struc::Channel::Msg_which_in</a></div><div class="ttdeci">typename Sync_io_obj::Msg_which_in Msg_which_in</div><div class="ttdoc">Stylistic nicety, indicating that a Msg_which applies to an in-message rather than an out-message.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00612">channel.hpp:612</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_ad3070c369762b2f5e85555155f65bdaa"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#ad3070c369762b2f5e85555155f65bdaa">ipc::transport::struc::Channel::unset_unexpected_response_handler</a></div><div class="ttdeci">bool unset_unexpected_response_handler()</div><div class="ttdoc">Undoes set_unexpected_response_handler().</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02585">channel.hpp:2585</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_ad3ff78f00b7f230562d713ec6cf8499c"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#ad3ff78f00b7f230562d713ec6cf8499c">ipc::transport::struc::Channel::Reader_config</a></div><div class="ttdeci">typename Sync_io_obj::Reader_config Reader_config</div><div class="ttdoc">Short-hand for the reader engine type.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00599">channel.hpp:599</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_ade399eda73424def3da0dd67596d2cff"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#ade399eda73424def3da0dd67596d2cff">ipc::transport::struc::Channel::Mutex</a></div><div class="ttdeci">flow::util::Mutex_non_recursive Mutex</div><div class="ttdoc">Short-hand for m_mutex (and similar) type.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01354">channel.hpp:1354</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_ade98da21ce433f8ba338e3139760e94a"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#ade98da21ce433f8ba338e3139760e94a">ipc::transport::struc::Channel::struct_lender_session</a></div><div class="ttdeci">const Builder_config::Builder::Session &amp; struct_lender_session() const</div><div class="ttdoc">Returns reference to immutable Builder_config::Builder::Session (a light-weight value,...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02039">channel.hpp:2039</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_ade9a8f99615d2c53de1a68989376750d"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#ade9a8f99615d2c53de1a68989376750d">ipc::transport::struc::Channel::struct_reader_config</a></div><div class="ttdeci">const Reader_config &amp; struct_reader_config() const</div><div class="ttdoc">Deserializing counterpart to struct_builder_config().</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02047">channel.hpp:2047</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_ae1f4b316eaeb7ed520a84d9e21e21063"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#ae1f4b316eaeb7ed520a84d9e21e21063">ipc::transport::struc::Channel::Msg_in_ptr</a></div><div class="ttdeci">typename Sync_io_obj::Msg_in_ptr Msg_in_ptr</div><div class="ttdoc">A ref-counted handle to Msg_in.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l00640">channel.hpp:640</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_ae645cb58ad9ea6374970f1f32c5da448"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#ae645cb58ad9ea6374970f1f32c5da448">ipc::transport::struc::Channel::send</a></div><div class="ttdeci">bool send(const Msg_out &amp;msg, const Msg_in *originating_msg_or_null=0, Error_code *err_code=0)</div><div class="ttdoc">In the synchronous/non-blocking manner of Blob_sender::send_blob() or Native_handle_sender::send_nati...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02276">channel.hpp:2276</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_aefee55a9e754a63ce52766d6c65df92c"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#aefee55a9e754a63ce52766d6c65df92c">ipc::transport::struc::Channel::m_sync_io</a></div><div class="ttdeci">Sync_io_obj m_sync_io</div><div class="ttdoc">The core struc::Channel engine, implementing the sync_io pattern (see util::sync_io doc header).</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01596">channel.hpp:1596</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_af0d9dcd9c3ccf8e064f0cca69b30ea25"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#af0d9dcd9c3ccf8e064f0cca69b30ea25">ipc::transport::struc::Channel::Lock_guard</a></div><div class="ttdeci">flow::util::Lock_guard&lt; Mutex &gt; Lock_guard</div><div class="ttdoc">Short-hand for Mutex lock.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01357">channel.hpp:1357</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1Channel_html_af9130e43dc985fca4a41f19581048b51"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1Channel.html#af9130e43dc985fca4a41f19581048b51">ipc::transport::struc::Channel::owned_channel_mutable</a></div><div class="ttdeci">Owned_channel * owned_channel_mutable()</div><div class="ttdoc">Access to mutable transport::Channel moved-into *this at construction.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l02641">channel.hpp:2641</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html">ipc::transport::struc::sync_io::Channel</a></div><div class="ttdoc">sync_io-pattern counterpart to async-I/O-pattern transport::struc::Channel.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00333">channel.hpp:337</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_a14a7166b2f8c117ce6ddafe943d036fa"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a14a7166b2f8c117ce6ddafe943d036fa">ipc::transport::struc::sync_io::Channel::Reader_config</a></div><div class="ttdeci">Struct_reader_config Reader_config</div><div class="ttdoc">See Async_io_obj counterpart.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00357">channel.hpp:357</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_a1572a1b1cb4a72ea57f7841a5e78759b"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a1572a1b1cb4a72ea57f7841a5e78759b">ipc::transport::struc::sync_io::Channel::Msg_which</a></div><div class="ttdeci">typename Message_body::Which Msg_which</div><div class="ttdoc">See Async_io_obj counterpart.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00363">channel.hpp:363</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_a34e183c252390f369f121074772c14c4"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a34e183c252390f369f121074772c14c4">ipc::transport::struc::sync_io::Channel::Msg_body</a></div><div class="ttdeci">Message_body Msg_body</div><div class="ttdoc">See Async_io_obj counterpart.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00360">channel.hpp:360</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_a4ab778bce8d7e6e84788879fedc62745"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a4ab778bce8d7e6e84788879fedc62745">ipc::transport::struc::sync_io::Channel::Msgs_in</a></div><div class="ttdeci">std::vector&lt; Msg_in_ptr &gt; Msgs_in</div><div class="ttdoc">List of in-messages used in certain APIs like expect_msgs() to synchronously emit cached in-messages.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00381">channel.hpp:381</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_a4abac89dbd4d26c79b7915990f751a76"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a4abac89dbd4d26c79b7915990f751a76">ipc::transport::struc::sync_io::Channel::Owned_channel</a></div><div class="ttdeci">Channel_obj Owned_channel</div><div class="ttdoc">See Async_io_obj counterpart.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00348">channel.hpp:348</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_a543aa806ec21b8550f9f440e59767d52"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a543aa806ec21b8550f9f440e59767d52">ipc::transport::struc::sync_io::Channel::replace_event_wait_handles</a></div><div class="ttdeci">bool replace_event_wait_handles(const Create_ev_wait_hndl_func &amp;create_ev_wait_hndl_func)</div><div class="ttdoc">Analogous to transport::sync_io::Native_handle_sender::replace_event_wait_handles().</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l02395">channel.hpp:2395</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_a6e4f8c4207fcf678b4cfc785707d3dce"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a6e4f8c4207fcf678b4cfc785707d3dce">ipc::transport::struc::sync_io::Channel::start_ops</a></div><div class="ttdeci">bool start_ops(Event_wait_func_t &amp;&amp;ev_wait_func)</div><div class="ttdoc">Sets up the sync_io-pattern interaction between *this and the user's event loop; required before star...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l02402">channel.hpp:2402</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_a7a731cdae5217ed9e867fb80c1fb0fd9"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a7a731cdae5217ed9e867fb80c1fb0fd9">ipc::transport::struc::sync_io::Channel::Msg_which_out</a></div><div class="ttdeci">Msg_which Msg_which_out</div><div class="ttdoc">See Async_io_obj counterpart.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00369">channel.hpp:369</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_a83fb4462a8d4045bdb56b694bf80393c"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a83fb4462a8d4045bdb56b694bf80393c">ipc::transport::struc::sync_io::Channel::Msg_out</a></div><div class="ttdeci">struc::Msg_out&lt; Msg_body, typename Builder_config::Builder &gt; Msg_out</div><div class="ttdoc">See Async_io_obj counterpart.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00372">channel.hpp:372</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_a8a59bbc3c6a7191b316b23661d8ba6e3"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a8a59bbc3c6a7191b316b23661d8ba6e3">ipc::transport::struc::sync_io::Channel::Builder_config</a></div><div class="ttdeci">Struct_builder_config Builder_config</div><div class="ttdoc">See Async_io_obj counterpart.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00355">channel.hpp:355</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_a9b5d17887c9ad1e37081bf4ae4a70e65"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#a9b5d17887c9ad1e37081bf4ae4a70e65">ipc::transport::struc::sync_io::Channel::msg_id_out_t</a></div><div class="ttdeci">Channel_base::msg_id_out_t msg_id_out_t</div><div class="ttdoc">See Async_io_obj counterpart.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00384">channel.hpp:384</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_aa40c3ec3f45cdfea9360f7f35b9ade3c"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#aa40c3ec3f45cdfea9360f7f35b9ade3c">ipc::transport::struc::sync_io::Channel::Msg_which_in</a></div><div class="ttdeci">Msg_which Msg_which_in</div><div class="ttdoc">See Async_io_obj counterpart.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00366">channel.hpp:366</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_ac3da0ac1306b63c9e38c47b8c31e3cd2"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#ac3da0ac1306b63c9e38c47b8c31e3cd2">ipc::transport::struc::sync_io::Channel::Msg_in</a></div><div class="ttdeci">struc::Msg_in&lt; Msg_body, Reader_config &gt; Msg_in</div><div class="ttdoc">See Async_io_obj counterpart.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00375">channel.hpp:375</a></div></div>
<div class="ttc" id="aclassipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_html_acde2b3866547a30958035203d9d89928"><div class="ttname"><a href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html#acde2b3866547a30958035203d9d89928">ipc::transport::struc::sync_io::Channel::Msg_in_ptr</a></div><div class="ttdeci">boost::shared_ptr&lt; Msg_in &gt; Msg_in_ptr</div><div class="ttdoc">See Async_io_obj counterpart.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_source.html#l00378">channel.hpp:378</a></div></div>
<div class="ttc" id="aclassipc_1_1util_1_1sync__io_1_1Asio__waitable__native__handle_html"><div class="ttname"><a href="classipc_1_1util_1_1sync__io_1_1Asio__waitable__native__handle.html">ipc::util::sync_io::Asio_waitable_native_handle</a></div><div class="ttdoc">Useful if using the sync_io pattern within a user event loop built on boost.asio (optionally with flo...</div><div class="ttdef"><b>Definition:</b> <a href="asio__waitable__native__hndl_8hpp_source.html#l00080">asio_waitable_native_hndl.hpp:81</a></div></div>
<div class="ttc" id="aipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_html_a5313383b4bb7158e2f65d89690348f04"><div class="ttname"><a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a5313383b4bb7158e2f65d89690348f04">CLASS_STRUCTURED_CHANNEL</a></div><div class="ttdeci">#define CLASS_STRUCTURED_CHANNEL</div><div class="ttdoc">See nearby TEMPLATE_... macro; same deal here.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01624">channel.hpp:1624</a></div></div>
<div class="ttc" id="aipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_html_a8646782bf9b3daa107f2aa818f6345cb"><div class="ttname"><a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a></div><div class="ttdeci">#define TEMPLATE_STRUCTURED_CHANNEL</div><div class="ttdoc">Internally used macro; public API users should disregard.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01620">channel.hpp:1620</a></div></div>
<div class="ttc" id="aipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp_html"><div class="ttname"><a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2sync__io_2channel_8hpp.html">channel.hpp</a></div></div>
<div class="ttc" id="anamespaceipc_1_1transport_1_1error_html_adfef15ef4e76cc55d652fbd9c2797297aa667487757f9d6300f6888bac40bcc24"><div class="ttname"><a href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297aa667487757f9d6300f6888bac40bcc24">ipc::transport::error::Code::S_SYNC_IO_WOULD_BLOCK</a></div><div class="ttdeci">@ S_SYNC_IO_WOULD_BLOCK</div><div class="ttdoc">A sync_io operation could not immediately complete; it will complete contingent on active async-wait ...</div></div>
<div class="ttc" id="anamespaceipc_1_1transport_1_1error_html_adfef15ef4e76cc55d652fbd9c2797297abcfca4c2347f9d377dd2ac41c41dc027"><div class="ttname"><a href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297abcfca4c2347f9d377dd2ac41c41dc027">ipc::transport::error::Code::S_TIMEOUT</a></div><div class="ttdeci">@ S_TIMEOUT</div><div class="ttdoc">A (usually user-specified) timeout period has elapsed before a blocking operation completed.</div></div>
<div class="ttc" id="anamespaceipc_1_1transport_1_1error_html_adfef15ef4e76cc55d652fbd9c2797297afe29343445a7bf167cc186a44bd2c6ed"><div class="ttname"><a href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297afe29343445a7bf167cc186a44bd2c6ed">ipc::transport::error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER</a></div><div class="ttdeci">@ S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER</div><div class="ttdoc">Async completion handler is being called prematurely, because underlying object is shutting down,...</div></div>
<div class="ttc" id="anamespaceipc_1_1transport_1_1struc_1_1shm_1_1classic_html_ac543b500a85f556564e592cbbefb6185"><div class="ttname"><a href="namespaceipc_1_1transport_1_1struc_1_1shm_1_1classic.html#ac543b500a85f556564e592cbbefb6185">ipc::transport::struc::shm::classic::Channel</a></div><div class="ttdeci">struc::Channel&lt; Channel_obj, Message_body, Builder::Config, Reader::Config &gt; Channel</div><div class="ttdoc">Convenience alias: Use this when constructing a struc::Channel with tag Channel_base::S_SERIALIZE_VIA...</div><div class="ttdef"><b>Definition:</b> <a href="transport_2struc_2shm_2classic_2classic_8hpp_source.html#l00041">classic.hpp:42</a></div></div>
<div class="ttc" id="anamespaceipc_1_1transport_1_1struc_html"><div class="ttname"><a href="namespaceipc_1_1transport_1_1struc.html">ipc::transport::struc</a></div><div class="ttdoc">Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifical...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8cpp_source.html#l00030">channel.cpp:31</a></div></div>
<div class="ttc" id="anamespaceipc_1_1transport_1_1struc_html_a6751c05fb6582a34c7c47ac470c4a48b"><div class="ttname"><a href="namespaceipc_1_1transport_1_1struc.html#a6751c05fb6582a34c7c47ac470c4a48b">ipc::transport::struc::Session_token</a></div><div class="ttdeci">boost::uuids::uuid Session_token</div><div class="ttdoc">A type used by struc::Channel for internal safety/security/auth needs.</div><div class="ttdef"><b>Definition:</b> <a href="struc__fwd_8hpp_source.html#l00113">struc_fwd.hpp:113</a></div></div>
<div class="ttc" id="anamespaceipc_1_1transport_1_1struc_html_ae272f248d74db0486c4d9411715db15d"><div class="ttname"><a href="namespaceipc_1_1transport_1_1struc.html#ae272f248d74db0486c4d9411715db15d">ipc::transport::struc::operator&lt;&lt;</a></div><div class="ttdeci">std::ostream &amp; operator&lt;&lt;(std::ostream &amp;os, const Heap_fixed_builder &amp;val)</div><div class="ttdoc">Prints string representation of the given Heap_fixed_builder to the given ostream.</div><div class="ttdef"><b>Definition:</b> <a href="heap__serializer_8cpp_source.html#l00132">heap_serializer.cpp:132</a></div></div>
<div class="ttc" id="anamespaceipc_1_1transport_html_a7ee4551983d9df16ec16a3139bac50e8"><div class="ttname"><a href="namespaceipc_1_1transport.html#a7ee4551983d9df16ec16a3139bac50e8">ipc::transport::Native_handle</a></div><div class="ttdeci">util::Native_handle Native_handle</div><div class="ttdoc">Convenience alias for the commonly used type util::Native_handle.</div><div class="ttdef"><b>Definition:</b> <a href="transport__fwd_8hpp_source.html#l00081">transport_fwd.hpp:81</a></div></div>
<div class="ttc" id="anamespaceipc_1_1util_1_1sync__io_html_ac6973c71fc70c6d867b0f2255c642532"><div class="ttname"><a href="namespaceipc_1_1util_1_1sync__io.html#ac6973c71fc70c6d867b0f2255c642532">ipc::util::sync_io::Task_ptr</a></div><div class="ttdeci">boost::shared_ptr&lt; Task &gt; Task_ptr</div><div class="ttdoc">Short-hand for ref-counted pointer to a Function&lt;&gt; that takes no arguments and returns nothing; in pa...</div><div class="ttdef"><b>Definition:</b> <a href="sync__io__fwd_8hpp_source.html#l00585">sync_io_fwd.hpp:585</a></div></div>
<div class="ttc" id="anamespaceipc_1_1util_html_ac66141280c3b7295a86b65209f31cc58"><div class="ttname"><a href="namespaceipc_1_1util.html#ac66141280c3b7295a86b65209f31cc58">ipc::util::Fine_duration</a></div><div class="ttdeci">flow::Fine_duration Fine_duration</div><div class="ttdoc">Short-hand for Flow's Fine_duration.</div><div class="ttdef"><b>Definition:</b> <a href="util__fwd_8hpp_source.html#l00117">util_fwd.hpp:117</a></div></div>
<div class="ttc" id="anamespaceipc_html_a4ccdeed058222c635745a4dc830e99f7"><div class="ttname"><a href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7">ipc::Log_component</a></div><div class="ttdeci">Log_component</div><div class="ttdoc">The flow::log::Component payload enumeration containing various log components used by Flow-IPC inter...</div><div class="ttdef"><b>Definition:</b> <a href="common_8hpp_source.html#l00322">common.hpp:323</a></div></div>
<div class="ttc" id="anamespaceipc_html_aa3192e586cc45d3e7c22463bf2760f89"><div class="ttname"><a href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">ipc::Error_code</a></div><div class="ttdeci">flow::Error_code Error_code</div><div class="ttdoc">Short-hand for flow::Error_code which is very common.</div><div class="ttdef"><b>Definition:</b> <a href="common_8hpp_source.html#l00298">common.hpp:298</a></div></div>
<div class="ttc" id="anamespaceipc_html_aa455c7f045059736578ca275fc1a851f"><div class="ttname"><a href="namespaceipc.html#aa455c7f045059736578ca275fc1a851f">ipc::Function</a></div><div class="ttdeci">flow::Function&lt; Signature &gt; Function</div><div class="ttdoc">Short-hand for polymorphic functor holder which is very common. This is essentially std::function.</div><div class="ttdef"><b>Definition:</b> <a href="common_8hpp_source.html#l00302">common.hpp:302</a></div></div>
<div class="ttc" id="astructipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_1_1Request__result_html"><div class="ttname"><a href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_1_1Request__result.html">ipc::transport::struc::Channel::Sync_op_state::Request_result</a></div><div class="ttdoc">A successul result of sync_request().</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01371">channel.hpp:1372</a></div></div>
<div class="ttc" id="astructipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_1_1Request__result_html_a2c7cde843910f748296c2c9ec406d99b"><div class="ttname"><a href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_1_1Request__result.html#a2c7cde843910f748296c2c9ec406d99b">ipc::transport::struc::Channel::Sync_op_state::Request_result::m_rsp</a></div><div class="ttdeci">Msg_in_ptr m_rsp</div><div class="ttdoc">Non-null response to out-message with ID Sync_op_state::m_originating_msg_id.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01374">channel.hpp:1374</a></div></div>
<div class="ttc" id="astructipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_html"><div class="ttname"><a href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html">ipc::transport::struc::Channel::Sync_op_state</a></div><div class="ttdoc">State in m_sync_op_state, when a sync-op is in fact in progress, meaning m_sync_op_state is not null.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01363">channel.hpp:1364</a></div></div>
<div class="ttc" id="astructipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_html_a5c49d5ee9989c5c0dc518868205687f0"><div class="ttname"><a href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#a5c49d5ee9989c5c0dc518868205687f0">ipc::transport::struc::Channel::Sync_op_state::m_op_done_signal</a></div><div class="ttdeci">boost::promise&lt; void &gt; m_op_done_signal</div><div class="ttdoc">In-traffic processing thread W, having set m_result_if_any to non-monostate, use m_op_done_signal....</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01408">channel.hpp:1408</a></div></div>
<div class="ttc" id="astructipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_html_a6b5142da7049fc212faff3914e69379b"><div class="ttname"><a href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#a6b5142da7049fc212faff3914e69379b">ipc::transport::struc::Channel::Sync_op_state::id_t</a></div><div class="ttdeci">unsigned int id_t</div><div class="ttdoc">ID of each sync operation: a distinct value is used each time a *this is created/placed into m_sync_o...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01368">channel.hpp:1368</a></div></div>
<div class="ttc" id="astructipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_html_ac8c083b7c861d00e2f987a017fbe994e"><div class="ttname"><a href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#ac8c083b7c861d00e2f987a017fbe994e">ipc::transport::struc::Channel::Sync_op_state::m_result_if_any</a></div><div class="ttdeci">std::variant&lt; std::monostate, Error_code, Request_result &gt; m_result_if_any</div><div class="ttdoc">Current state of the in-progress sync-op (as of this writing, there is only sync_request()).</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01390">channel.hpp:1390</a></div></div>
<div class="ttc" id="astructipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state_html_ad6f8e016b2abc3654e1915cc8c77c268"><div class="ttname"><a href="structipc_1_1transport_1_1struc_1_1Channel_1_1Sync__op__state.html#ad6f8e016b2abc3654e1915cc8c77c268">ipc::transport::struc::Channel::Sync_op_state::m_id</a></div><div class="ttdeci">id_t m_id</div><div class="ttdoc">See id_t; used to check an arriving sync op result as belonging to the currently-waiting sync op.</div><div class="ttdef"><b>Definition:</b> <a href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp_source.html#l01380">channel.hpp:1380</a></div></div>
<div class="ttc" id="astructipc_1_1transport_1_1struc_1_1Heap__fixed__builder_1_1Config_html"><div class="ttname"><a href="structipc_1_1transport_1_1struc_1_1Heap__fixed__builder_1_1Config.html">ipc::transport::struc::Heap_fixed_builder::Config</a></div><div class="ttdoc">Implements Struct_builder::Config sub-concept.</div><div class="ttdef"><b>Definition:</b> <a href="heap__serializer_8hpp_source.html#l00154">heap_serializer.hpp:155</a></div></div>
<div class="ttc" id="astructipc_1_1transport_1_1struc_1_1Heap__reader_1_1Config_html"><div class="ttname"><a href="structipc_1_1transport_1_1struc_1_1Heap__reader_1_1Config.html">ipc::transport::struc::Heap_reader::Config</a></div><div class="ttdoc">Implements Struct_reader::Config sub-concept.</div><div class="ttdef"><b>Definition:</b> <a href="heap__serializer_8hpp_source.html#l00332">heap_serializer.hpp:333</a></div></div>
<div class="ttc" id="astructipc_1_1util_1_1Native__handle_html"><div class="ttname"><a href="structipc_1_1util_1_1Native__handle.html">ipc::util::Native_handle</a></div><div class="ttdoc">A monolayer-thin wrapper around a native handle, a/k/a descriptor a/k/a FD.</div><div class="ttdef"><b>Definition:</b> <a href="native__handle_8hpp_source.html#l00062">native_handle.hpp:63</a></div></div>
</div><!-- fragment --></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Apr 11 2025 20:02:25 for Flow-IPC by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
